Markdown based html generator.
Project description
Markdown based html generator. Generation requires: HTML template and markdown template. Additional meta-extensions allow you to add metaprogramming to this process.
Installation
pip install mdhtmlgen
Usage
$ python -m mdhtmlgen --help
Usage: python -m mdhtmlgen [options]
Options:
-h, --help show this help message and exit
-S SOURCE, --source=SOURCE
Markdown source filename (*.md)
-H HTML, --html=HTML HTML template filename (*.t)
-t, --trace Print diagnostic traces
-o OUTPUT, --output=OUTPUT
Set output file
-m MARKDOWN_EXT, --markdown-ext=MARKDOWN_EXT
Set markdown extension list, coma separated, e.g.
meta,toc,footnotes
-d DATE_FMT, --date-fmt=DATE_FMT
Set date format, e.g. %d-%m-%Y %H:%M:%S
-e EXT, --ext=EXT Set extension list, e.g. meta,glob,filename,date
-a PARAMS, --add=PARAMS
Add parameter in format name:value
-g GIT_DIR, --git-dir=GIT_DIR
Set GIT directory location, e.g. /home/user/repo/.git
Tools
We use python as the template engine for html and markdown, and its ingenious feature is string formatting using a dictionary.
A simple example:
print('Dear %(name)s, I am interested in the %(post)s position at your company…' % {'name': 'Oliver', 'post': 'Sales Manager'})
Here name and post are template parameters. If you understand how this example works, then there will be no problems with the rest.
Markdown itself does not generate html. Markdown is responsible for the content, so we use an additional page template to generate the html.
Example
Let's create a simple page template - html.t:
<!DOCTYPE html>
<html>
<head>
<title>%(title)s</title>
<meta charset="utf-8" />
<link rel="stylesheet" href="styles.css" />
</head>
<body>%(body)s</body>
</html>
Now let's add a content template for this page - example.md:
---
title: Example Page
---
## Task scenario
You want to buy traveler’s checks with your credit card. Which percentage rate applies to the purchase?
*Possible answers:*
* The Standard APR of 10.99%
* The Cash Advance APR of 24.24%[^*]
* The Penalty APR of 29.99%
* I don’t know
[^*]: This is the correct answer, based on my own credit card company’s cardmember agreement.
The last step is to combine 2 templates into 1 html:
$ python -m mdhtmlgen -S example.md -H html.t -o example.html
The same can be done via a redirect:
$ python -m mdhtmlgen -S example.md -H html.t >example.html
Whichever is more convenient - the result will be the same.
As you can see, In HTML template was added styles.css. For our example, we can take ready styles, for example from the sindresorhus/github-markdown-css project, they cover the markdown functionality.
But if it is not enough for you, you can always extend html.t, add links to additional styles and scripts.
Extensions
Without extensions, markdown is very limited. A list of basic extensions can be found on the markdown github page.
Into mdhtmlgen, you can pass a list of extensions to be used during generation using the -m or --markdown-ext option.
Besides the markdown extensions, mdhtmlgen has its own meta extensions. At the moment there are 6 of them:
filename
Adds path information to the template for the source:
%(input-path)s- full source path%(input-name)s- name of source file%(input-ext)s- extension of source filename%(input-basename)s- basename of source
and similar information about the output:%(output-path)s%(output-name)s%(output-ext)s%(output-basename)s
date
Adds information about the date and time of the last modification of the source to the template -%(input-date)sgitdate
Adds to the template information about the date and time of the last modification of the source in the Git repository -%(input-git-date)s.
For this extension, you need to specify the path to the repository using the--git-diroption (a similar option exists in Git, seeman git).custom
Allows you to add arbitrary meta-parameters to the template using the option-aor--addmeta
Imports a meta-parameter from another source into a template, example:%(input-file-date:other-example.md)s.
Here we have extracted%(input-file-date)sfrom theother-example.mdsourceglob
Concatenates meta parameters from different sources, example:%(glob:row:*.md)s.
Here we have concatenated%(row)sfrom all sources using the search pattern*.md.
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
