Build html wiki-like structure from markdown.
pip install git+https://github.com/automateship/markdownship.gitTo build a single html file from markdown, use this command:
python -m markdownship build -t template markdown_file.mkd -o output_file.htmlIf you omit -o option, output file will be in current dir with same name as
input markdown file but with .html extension.
If you omit -t option, default template will be used.
Let's say that we have directory tree with markdown files in it like this:
[/home/user/documentation]
├── introduction.mkd
├── [first_section]
│ ├── doc_a.mkd
│ └── doc_b.mkd
└── [second_section]
├── doc_1.mkd
├── doc_2.mkd
└── [subsection]
├── doc_3.mkd
└── doc_4.mkd
and that we want to convert it to html that will be in /var/www. This is how
we do it:
python -m markdownship build /home/user/documentation -o /var/www/my_wiki -u http://my.wiki.com/Now we will get this:
[/var/www/my_wiki]
├── index.html <------------
├── introduction.html
├── [first_section]
│ ├── index.html <--------
│ ├── doc_a.html
│ └── doc_b.html
└── [second_section]
├── index.html <--------
├── doc_1.html
├── doc_2.html
└── [subsection]
├── index.html <----
├── doc_3.html
└── doc_4.html
Note the index.html files that are generated. These will contain only table
of contents and nothing more. If you want them to hold some contents, then
create index.mkd file in each directory of your /home/user/documentation
dir.
Note the -u option that we used. It is used to specify root URL of the wiki.
If you have some links inside markdown files, just use %url% tag before the
relative path and markdownship will replace it with what is specified by -u.
Default data dir is named \_data and should be located in wiki's root
directory. When you use build command, this directory is copied as is to the
output root. If you use images in markdown files, you can put them in data dir
and use links to them such as %url%/_data/images/test.png.
Data dir also contains several special markdown files.
These are located in root of the data dir (default ./_data/).
Put a file named header.mkd in data dir and it will be used to create header
for the site.
Just as header, footer also has a special file in data dir and is named
footer.mkd.
Add a favicon for your site in data dir and name it favicon.ico. It can be in
png and other formats, as long as you keep the same name.
If you don't want a generated toc and want to define your own, put a file named
toc.mkd in your data folder and it will be used instead of generated toc.
To get a list of existing templates just call this command:
python -m markdownship list_templatesTo specify what template to use during build, just use a -t option. Example:
python -m markdownship build -t dark markdown_file.mkd -o output_file.htmlTo use a custom created template that is not a part of a package, use -T
option. Example:
python -m markdownship build -T ~/custom_template.html markdown_file.mkd -o output_file.htmlTemplates are dummy html files that look something like this:
<html>
<head>
<style type="text/css">
</style>
</head>
<body>
%header%
%toc%
%markdown%
%footer%
</body>
</html>%header%tag will be replaced with header div with id 'header'.%toc%tag will be replaced with table of contents in a div with id 'toc'.%markdown%tag is replaced by contents of markdown file. It will be in a div with id 'markdown'.%footer%is replaced by footer div with id 'footer'.
You can use custom divs as wrappers for these and define custom css styles.
Tags are specific string in markdown files that are used as placeholders for data generated by markdownship.
Usage of %toc% and %markdown% tags is already explained in
creating templates section above.
url tag is used to represent base url of the wiki. If you want to have a link
in markdown file that refers to another markdown file, then use this as a path
string: %url%/wiki_root_dir/path/to/file.mkd.
More info on tags in help: python -m markdownship build -h.
I use this entry in my vimrc. When I vim into some markdown file for editing,
I can press F9 to open the same document in web browser for better display.
This script converts the markdown file to html in /tmp directory, fires a
browser and finaly deletes the file from /tmp when I'm done viewing:
set shell=/bin/bash
:map <F9> :!python -m markdownship build -o /tmp/`basename %`.html %; x-www-browser /tmp/`basename %`.html; rm /tmp/`basename %`.html<CR><CR>