Overview

pymdWiki

HTML generator for offline markdown files (v1.3.0)
Generates a collection of HTMLs from offline markdown files and uploads them to your ftp server. Simple as that!
This program is based on pypi Markdown and use that to generate HTML bodies from individual markdown files.

Features

  • Lightweight command line utility
  • Preserves links and images
  • Automatic FTP upload
  • Creates identical directory tree for HTML files
  • Themes with JSON config files
  • Automatic table of contents (TOC) generation

Windows binaries

For windows users who doesn't want to bother with python, You can download latest stand-alone binaries from
here.

Installation

You just have to install these requirements to be able to run from source:

  • Python 2.7: Install Python binaries for your OS. (link)
  • Markdown for python: Follow the instructions here for installing this package for python.

Usage

Download binaries or the source and:

cd /path/to/pymdwiki/src
python mdwiki.py --help

to see command line options.
For stand-alone distribution, typing the executable is sufficient:

cd path/to/mdwiki
mdwiki --help

Command line options

  • --input [inputdir]: Sets input root directory which mdwiki searches for (.md) files recursively. Default path is the current directory.
  • --output [outputdir]: Sets output root directory which mdwiki writes HTML files, directories will be created exactly like the input directories (if they contain .md files). Default path is ./html
  • --ftp [server]: If this argument is set, after generating HTML files, the program will connect to remote ftp server and upload HTML files to it. The user should also input his/her ftp username/password upon connection. [server] can contain port number and extra install paths on the remote server, here are some examples:
    • --ftp ftp.myhost.com
    • --ftp ftp.myhost.com:336
    • --ftp ftp.myhost.com:336/public_html/wiki/
  • --theme: Name of theme to be used for HTML pages, see Themes for more info.
  • --verbose: Enable verbose messages

Themes

Themes are referenced by their names which is basically their directory names under themes directory. For example one of the bundled themes are darkhammer, which is a directory with the same name under path/to/pymdwiki/themes.

Making new themes

To create themes you should create a directory under themes directory and put these files into it:

  • tmpl.html: This is the main template file for the theme, any header/footer html code and css or javascripts can be referenced in this file. You can use predefined variables and include them inside this file, the theme compiler will fill out those variables upon mdwiki compilation. Here is the list of those variables:

    • $(CONTENT): HTML content generated from .md files go there.
    • $(THEMEPATH): mdwiki will put the path to the current theme for this variable.
    • $(PREFIX): Prefix path should come before any resource files for the theme
    • $(TITLE): Title of the wiki
    • $(FOOTNOTE): User footnote for the footer
    • $(LOGO): Can be a relative path to an image for the wiki
  • config.json: This is settings JSON file for the theme, includes common variables for theme compiler. mdwiki will read this file and fillup some template tags:

    • title: will set $(TITLE) value upon HTML generation (see above)
    • footnote: will set $(FOOTNOTE)
    • logo: will set $(LOGO)
    • code-theme: name of the code highlighting theme file (which is .css), css files are under /css directory and you can preview them in highlight.js

Note that the program only reads all (png, jpg, css, js, gif) files under theme root path (not recursive) and copy them to ouput HTML path or upload them to ftp, so don't bloat the main directory for the theme with unnecessary files.

Table of contents (TOC): To Embed TOC in your theme, there is a jquery plugin available inside the package, that you should integrate it inside your tmpl.html, here's how:
Add main.css to theme styles:

<link rel='stylesheet' href='$(PREFIX)css/main.css'>

Create a div somewhere in HTML, (likely in the sidebar area):

<div id='toc'>
</div>

At the end of the page, add jquery.js and toc.js included with the package and initialize toc plugin:

<script src='$(PREFIX)js/jquery-1.9.1.min.js'></script>
<script src='$(PREFIX)js/toc.js'></script>
<script>
    $('#toc').mdwikiTOC();
</script>

Bundled Themes: Current bundled themes are default and darkhammer. default theme is always applied even if you don't define any theme. darkhammer as the name suggests, is a dark theme mainly built for my other open-source project with the same name.

License

License for source code and redistribution is BSD 2-Clause

Credits

Sepehr Taghdisian (sep.tagh@gmail.com)