markdownship

Build html wiki-like structure from markdown.

how to install

pip install git+https://github.com/automateship/markdownship.git

build single file

To build a single html file from markdown, use this command:

python -m markdownship build -t template markdown_file.mkd -o output_file.html

If 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.

build wiki-like structure

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.

data dir

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.

special markdown files

These are located in root of the data dir (default ./_data/).

header

Put a file named header.mkd in data dir and it will be used to create header for the site.

footer

Just as header, footer also has a special file in data dir and is named footer.mkd.

favicon

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.

templates

using templates

To get a list of existing templates just call this command:

python -m markdownship list_templates

To 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.html

To 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.html

creating custom templates

Templates 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.

other uses

vimrc entry

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>

nul-one / markdownship