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. The default templates are:
-
simple
: A simple one column layout using Bootstrap, with support for math (using MathJax), syntax highlighting, and automatic light/dark theme switching. (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
-
Clone the repository https://codeberg.org/gi1242/md-to-html.git
-
If you use
pip
, then install by:pip install '/path/to/md-to-html[resize,codehilite]'
-
If you don't use
pip
, create a symlink tosrc/md-to-html
from somewhere in your path. In this case you may also have to install the dependencies:- Required dependencies: python, python-frontmatter, python-jinja, python-markdown, python-pyxdg.
- Optional dependencies: python-pillow (for resizing images), python-pygments (for syntax highlighting output).
Usage
Simple one file use case
Just run md-to-html file.md
to produce file.html
.
(Optionally choose template / set options in the YAML front matter.)
More complicated multi-file use case
To build more complicated sites, this will do two things for you:
-
Recurse directories and create HTML files (either in the same location, or in a specified destination directory preserving the hierarchy).
-
Recurse through the destination directory, and purge all HTML files that don't correspond to markdown source files. (You can set exclude / preserve lists.)
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 [[examples/livereload/index.html|here]]).
-
Automatically reload the HTML preview when the HTML is compiled. I use a
livereload
server (instructions [[examples/livereload/index.html|here]]).
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 Show extra html files
-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)
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 (hardcoded) options are:
:::yaml
enable_mathjax: true
enable_codehilite: true
enable_jinja: false
jinja_header: |
{%- import 'lightgallery.j2' as LightGallery -%}
template: simple
encoding: utf-8
absolute_links: False
update: False
exclude_dirs: [
'.git'
'__pycache__'
'templates'
'reveal.js'
]
exclude_files: []
protect_dirs: [
'reveal.js'
]
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.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.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 -
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
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">
These are only documented in the source 😄
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
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.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 65aaeb964ce00ef89329d8700a43cf69ead12f25281df9d49e5738303f9fd834 |
|
MD5 | 776bdeb4dd52212b1bde5b6d2ed605be |
|
BLAKE2b-256 | 4ff4b53ac4cc4da0ba2d64ca00295a8bce5ab1b972cb46453bc21e1552fdb48d |