diff options
author | Zhiming Wang <zmwangx@gmail.com> | 2015-12-31 14:16:59 -0800 |
---|---|---|
committer | Zhiming Wang <zmwangx@gmail.com> | 2015-12-31 14:19:27 -0800 |
commit | c92e064e0d2d8ec6b719c92f97e905418b67a755 (patch) | |
tree | 52685d4d0f980b5103967ee6dcdae8f8963ac30a /README.md | |
parent | 927a9d82f579598d29746f77d320a5ec1b250f53 (diff) | |
download | my_new_personal_website-c92e064e0d2d8ec6b719c92f97e905418b67a755.tar.xz my_new_personal_website-c92e064e0d2d8ec6b719c92f97e905418b67a755.zip |
README.md: Add section "Markdown features of pyblog"
Document my new image size Markdown extension, and other HTML
transforms.
Diffstat (limited to 'README.md')
-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. |