Convert Markdown to HTML using Jinja2 templates
Project description
Convert Markdown to HTML using Jinja2 templates
This converts a markdown file to a full HTML file by using a template. Can be used to make small standalone HTML documents, or larger multi-page sites. The default templates are:
-
simple
: A simple one layout using Bootstrap. -
navright
: Likesimple
, but includes a navigation column on the right for medium screens. (See a demo here.) -
A LightGallery slideshow. (See a demo here.) (This script can also resize your original images and create thumbnails / web versions for your slideshow. See the demo for instructions.)
Installation
-
Using pip: Run
pip install "md-to-html2[resize,codehilite]"
. (Note the extra2
; the namemd-to-html
was already used on PyPi 🙄.) -
On Arch Linux: Install
md-to-html2
from the AUR either manually, or using a helper. -
Installing manually
-
Clone the repository https://codeberg.org/gi1242/md-to-html.git
-
Create a symlink to
src/md-to-html
from somewhere in yourPATH
. -
Install the required dependencies: python, python-frontmatter, python-jinja, python-markdown, python-pyxdg.
-
Optionally install the optional dependencies: python-pillow (for resizing images), python-pygments (for syntax highlighting output).
-
Usage
One page use case
Just run md-to-html file.md
to produce file.html
.
This is good for creating a simple webpage, RevealJS presentation, LightGallery slideshow.
Optionally choose template / set options in the YAML front matter.
Multi-page use case
To build more complicated sites, this script can do two the following:
-
Recurse directories and create HTML files (either in the same location, or in a specified destination directory preserving the hierarchy).
-
Resize images to create thumbnails / web-versions for your slideshows.
-
Move JavaScript / CSS to a separate shared directory, instead of inlining them.
-
Recurse through the destination directory, and purge all HTML files that don't correspond to markdown source files. (You can set exclude / preserve lists.)
-
Run external commands you can use to copy static files (e.g. CSS / JS).
To build a website, you may need a few other things. This script doesn't do them because there are other tools that do them excellently. For example:
-
Copying static files, or uploading to your web server. I use
rsync
for this. (You can configure this script to runrsync
or any external command on successful completion using theexec
option in config files.) -
Automatically watch files and compile HTML when the source is changed. I configured my editor (Neovim) to do this automatically every time a source file is changed (instructions here).
-
Automatically reload the HTML preview when the HTML is compiled. I use a
livereload
server (instructions here).
Example
Look in site-config.yaml
for an example that generated this site
Command line options
usage: md-to-html [-h] [-c CONFIG] [-d] [-f] [-F] [-n] [-q] [-R] [-r] [-s]
[-p PREVIEW] [-t THREADS] [-u] [-v]
[files ...]
Convert markdown files to HTML using Jinja2 templates
positional arguments:
files Markdown (or YAML config) files
options:
-h, --help show this help message and exit
-c CONFIG, --config CONFIG
Config file (YAML)
-d, --delete-extra Delete extra html files
-f, --force Render whether or not source is newer
-F, --force-resize Resize images whether or not source is newer
-n, --no-exec Don't run commands specified by 'exec'
-q, --quiet Suppress info messages
-R, --no-recurse Recurse subdirectories for *.md files
-r, --resize-images Resize images for slideshows
-s, --show-extra Show extra html files
-p PREVIEW, --preview PREVIEW
Launch preview for output file (no output is
generated)
-t THREADS, --threads THREADS
Number of threads. Use 0 (default) to let the system
decide automatically.
-u, --update Only render if source is newer
-v, --verbose Show debug messages
Configuration (from YAML config files)
In addition to config files supplied with -c
, the following directories are searched for configuration.
- The directory this script was installed in
/etc/xdg/md-to-html
~/.config/md-to-html
- The directory of the input file.
Global options should be in a config.yaml
file.
The default options are:
enable_mathjax: true
enable_codehilite: true
enable_jinja: false
jinja_prefix: 'jinja '
jinja_header: >
{%- import 'lightgallery.j2' as LightGallery -%}
template: simple
standalone: true
toc_depth: 2-4
encoding: utf-8
base_url: '' # Include trailing slash
shared_dir: shared/md-to-html
absolute_links: false
update: false
exclude_dirs:
- .git
- __pycache__
- templates
- reveal.js
exclude_files: []
protect_dirs:
- reveal.js
- /shared/md-to-html
protect_files: []
base_dir
: Base of the source directory hierarchy. Source file outside this directory will raise an exception. (Default.
.) It is treated as a relative path from the file it was defined in, so thatbase_dir: .
works as expected.dst_dir
: All output goes in this directory, preserving the directory hierarchy up tobase_dir
. That isbase_dir/path/file.md
becomesdst_dir/path/file.html
. It is treated as a relative path from the file it was defined in.shared_dir
: For non-standalone documents, put CSS / JS here.standalone
: If true, all CSS / JS is included inline.base_url
: Base URL of the target site. Shared files should accessible atbase_url/shared_dir
. If empty, then relative paths will be used for shared files.dst_file
: Destination file name (relative todst_dir
). If unspecified, use the source file name with.html
extension.exclude_files
/exlcude_dirs
: List of glob patterns of source files / directories to ignore when recursing through directories. (Values are appended to existing values; to clear the list use!!reset
as the first entry.)protect_files
/protect_dirs
: List of glob patterns of destination files / directories to protect from deletion. When-d
is used, all HTML files in the destination directory that do not correspond to source markdown files are deleted.protect_files
/protect_dirs
can be used to protect some of these files from deletion. (Values are appended to existing values; to clear the list use!!reset
as the first entry.)sources
: List of source files / directories to convert to HTML / recurse into. (Ignored if files are present on command line.)update
: Only compile source if it is newer than the target HTML (overridden by-u
/-f
on command line)exec
: Commands to run if all files are processed without error (must be defined in a YAML config file specified with-c
) Useful to startrsync
to transfer static files. Multiple commands can be given if separated by newlines. All commands are passed through a shell, and run inbase_dir
.
Configuration (from YAML front matter)
All metadata, including the template name, can also be specified as YAML front matter surrounded by ---
:
---
template: simple
encoding: utf-8
enable_jinja: true
---
Markdown content starts here.
Markdown Syntax and Extensions
We use python-markdown to render the HTML, with the following extensions enabled:
-
Extra: A compilation of various Python-Markdown extensions that (mostly) imitates PHP Markdown Extra. The supported extensions include: Abbreviations, Attribute Lists, Definition Lists, Fenced Code Blocks, Footnotes, Tables, Markdown in HTML.
-
Sane Lists: The Sane Lists extension alters the behavior of the Markdown List syntax to be less surprising.
-
SmartyPants: The SmartyPants extension converts ASCII dashes, quotes and ellipses to their HTML entity equivalents.
-
Table of Contents: The Table of Contents extension generates a Table of Contents from a Markdown document and adds it into the resulting HTML document. (Use it either in templates via
{{toc}}
or in markdown after settingenable_jinja: true
.) -
Strikethrough:
Producestrike throughtext using~~text~~
-
CodeHilite: The CodeHilite extension adds code/syntax highlighting to standard Python-Markdown code blocks using Pygments. (Disable it with
enable_codehilite: false
) -
Wiki Links:
To use[[link.html|label]]
syntax (and provide warnings if the link is to a local find and isn't found. -
Math
: Render math using MathJax. For example: $\displaystyle f(z) = \frac{1}{2\pi i} \oint_{\abs{z - \zeta} = r} \frac{f(\zeta)}{z - \zeta} , d\zeta ,. $ -
Jinja2 expressions if
enable_jinja
is true (default is false).
MathJax Macros and options
A few MathJax options and LaTex macros are defined in the simple.j2
template.
To add your own macros or change the mathjax configuration, you have a few options:
-
For new macros in one document use this at the start of the file:
$ \newcommand{\mymacro}{expansion} ... $
-
For per document configuration changes use the
mathjax_config
YAML metadata.:::yaml --- mathjax_config: | MathJax.tex.tags = 'ams' MathJax.tex.macros = { ...MathJax.tex.macros, sign: '\\operatorname{sign}', abs: [ '#1\\lvert#2#1\\rvert', 2, '' ] } ---
The contents of
mathjax_config
are treated as JavaScript and included right after theMathJax
configuration object is defined. You can, for instance, also define (or undefine) macros usingMathJax.tex.macros
. (If you put this inconfig.yaml
, then it will be used for all files in that directory.) -
For more global settings, you can extend the template and override the
mathjax
block (look attests/templates/custom.j2
for an example).
WikiLinks
Use [[file.html|label]]
to generate a link to file.html
with label label
.
To use the file name as the label, just use [[file.html]]
- Link to files which don't exist produce a warning.
[[/absolute/path]]
links tobase_url/absolute/path
.- If
absolute_links
is set, then all wiki-links are converted to absolute links usingbase_url/absolute/path
.
Using Jinja2 commands in the markdown file.
By default Jinja2 expressions are only available in templates, and not in the markdown file.
If you want to use them, set enable_jinja=true
in either the metadata or global configuration options.
For example:
:::markdown
---
title: Document tile
author: Author
template: simple
enable_jinja: true
user_flag: true
---
# {{title}}
*{{author}}, 2023-10-06*
You can use Jinja2 expressions: 1 + 1 = {{1 + 1}}.
{% if user_flag %}
You can set conditionals in metadata
{% else %}
and render content based on the values.
{% endif %}
Note: enable_jinja=false
by default so invalid Jinja2 expressions don't surprise users.
Templates
A file is converted to HTML using a Jinja2 template.
Templates should be in the templates
subdirectory of one of the configuration folders, and should have a .j2
extension.
A bare bones example of a template is:
:::jhtml
<!DOCTYPE html>
<html>
<head><title>{{title}}</title></head>
<body>{{content}}</body>
</html>
All YAML metadata and global options are accessible as template variables. The following additional variables are defined while processing:
- uses_math: True if math was detected when rendering the file
- uses_codehilite: True if syntax highlighted code was detected when rendering the file
- toc: HTML table of contents obtained from the file
- title: Contents of the first
<h1>
element, if not previously set. - content: Document content after conversion from Markdown to HTML
Extensions
-
Convert the contents of the
var
from markdown to HTML by{{var|markdown}}
. -
Convert an arbitrary block of markdown to HTML using
{% markdown %}... {% endmarkdown %}
.
Template specific options
There are various template specific options that can be set from YAML front matter (or config files).For instance, to add a style sheet, you can use
end_head: <link href="..." rel="stylesheet" integrity="..." crossorigin="anonymous">
Live Previews
You can have the web browser automatically reload the HTML preview every time you make a change. Two ways of doing this are described in examples/livereload/index.md
md-to-html Copyright 2023, Gautam Iyer. MIT Licence.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for md_to_html2-0.3-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 2329b480814015962e6515ee93850bda6fcb8b68c87286b5587096d58b123eb9 |
|
MD5 | 73773f06c31e4df38d166bc29a0e36d5 |
|
BLAKE2b-256 | af67c3366820064905f00f9a875f7a2347b5db455ae21331fc727fa0790a067f |