diff options
| -rw-r--r-- | README.md | 55 |
1 files changed, 55 insertions, 0 deletions
@@ -18,3 +18,58 @@ Note that `pyblog` is incompatible with Python 2.x, and in fact only tested on P The theme of this blog is largely based on that of [mort.ninja](http://mort.ninja) by [Mort Yao](https://github.com/soimort). See [this post](https://zmwangx.github.io/blog/2015-05-05-new-blog-new-start.html) for more details. Self-hosted Google Web Fonts are downloaded from [google-webfonts-helper](https://google-webfonts-helper.herokuapp.com/fonts), courtesy of [Mario Ranftl](http://ranf.tl/2014/12/23/self-hosting-google-web-fonts/). + +## Markdown features of `pyblog` + +`pyblog` uses Pandoc for Markdown processing. The HTML template is +located in [`templates/`](templates). + +Beyond Pandoc's standard Markdown to HTML conversion, `pyblog` +postprocesses Pandoc-generated HTML to add a few Markdown extensions and +blogging-friendly HTML transforms. + +### Markdown extensions + +#### Image size + +Allows specifying image size in a Markdown image construct `![]()`. The +syntax is: + +  + +where `width` and `height` are positive integers (`xheight` is +optional), and `alt` is the regular `alt` string (either plain or with +some Markdown formatting). The `alt` string, as usual, is optional. + +Examples: + +  +  +  + +See `process_image_sizes` in [`pyblog`](pyblog). + +### Other HTML transforms + +#### Line-numbering in preformatted code blocks + +Line numbers are added to preformatted code blocks. Note that this +transform is only applied to `pre` tags with class `sourceCode lang`, +where `lang` is any language, so one must use a fenced code block with +language spec in the Markdown document to take advantage. + +See `number_code_lines` in [`pyblog`](pyblog). + +#### Link images to originals + +`img` tags are automatically converted to clickable links to their +originals (with `target="_blank"` so the original is opened in a new +tab). + +See `link_img_tags` in [`pyblog`](pyblog). + +#### Footnote backlinks + +Pandoc Markdown has footnote support, but unfortunately doesn't support +backlinks. This transform inserts a backlink to the end of each +footnote so that readers won't get lost after finish reading a footnote. |