I am currently in the process of documenting my workflow for several quantum chemical calculation-types. There are many ways in which I could do this, but I decided to use simple Markdown->HTML conversion for this task.
For writing long texts and having nice-to-look-at formatting Latex is probably the go-to option for most scientists. For the sake of having a HTML page at the end, Latex2HTML conversion is also a possible option. However, formatting can be a bit tedious at some points, as formatting characters like , { and } are not accessible on a QWERTZ keyboard layout without disrupting your writing flow in some form.
In this regard, Markdown (md) is a much nicer option, as formatting characters like _ and * can be reached more easily and formatting is limited to the most basic functions. For short to mid-length texts this is totally appropriate in my opinion, with the added benefit of faster typing. There are also md2html converters available which made this choice even more appealing.
These converters, though, give you HTML pages with their (basic) style. If you want your own (slightly fancier) styling, editing HTML files is not an option, because you need to find special identifiers for different blocks like code-environment, lists, tables, and so on.
So I decided to write my own md2html parser, which turned out to be easier than expected. Most md capabilities are preserved (basically everything except for unlimited nesting of lists) and some extended while keeping the standard syntax mostly intact (differences: links, images, table cell format).
Features of this converter include:
The included example md files can be found here: https://t-rkr.de/md2html/content – and the generated HTML files here: https://t-rkr.de/md2html/html. The script itself will be made available later, when I have prepared a designated presentation and download area (if not simply posted to GitHub).
$ md2html.pl -h
_ ___ _ _ _ _
| |__ \| | | | | | | |
_ __ ___ __| | ) | |__ | |_ _ __ ___ | | _ __ | |
| '_ ` _ \ / _` | / /| '_ \| __| '_ ` _ \| | | '_ \| |
| | | | | | (_| |/ /_| | | | |_| | | | | | |_| |_) | |
|_| |_| |_|\__,_|____|_| |_|\__|_| |_| |_|_(_) .__/|_|
| |
v23-01-2020 |_|
This script generates HTML files from markdown text files.
The basis md syntax is kept, but extended at some points:
- (default:) place md files in a folder 'content', HTML files
will be printed to a folder 'html'
- Files must start with '### File caption'
- Sections are started with a single # + white space(!): '# Section caption'
- Sections can get IDs which will appear at the header bar on each
site + the TOC: '#my_id Section caption'
- _italics_, __bold__, ___italics+bold___, `inline code`
- Code block lines must start with '>' (everything in this block will be shown verbose)
- Images+captions can be included as !../my/link/to/img.svg,Figure caption
alternatively you can also give widht and height of the image in %:
! ../img.png,width,height,caption
(must be in a separate line in the markdown file!)
- Link format nearly identical to MD: !
Added ! and the end allows for bracketed text in the link text + the rest of the line
- Tables must start with |; format:
| text | will be centered,
|> text | will be right aligned,
|< text| will be left aligned
- Lists start with * or 1.
- Only allowing for one nested list (add whitespace(s) before */1.)
- Ordered and unordered lists can be mixed
- table of contents will be generated in-place at keyword: !TOC!
Note: if not used in a file called 'index', this will not contain all links!
- ----- will add a line with navlinks to top/index
Modified/added CSS items + classes:
body, h1, h2, a, a:link, a:visited, a:active, a:hover, a.imglink, a.toc,
a.toc:hover, div, div.main, div.code, div.img, div.navmenu, div.caption,
div.table, div.toc, div.text, div.footer, span.inline-mono, table, th, td,
ul, ol, .nested
Usage:
md2html.pl [-keywords...]
Keywords:
-example: Prints example files
-clean: Removes example files
-cf [string]: Set the name of the folder containing the MD files. (Default: content)
-of [string]: Set the name of the output folder. (Default: html)
-pcol [string]: Set the primary color. (Default: rgb(107,174,214))
-scol [string]: Set the secondary color. (Default: rgb(253,187,45))
Note: Both can also be hex codes, or rgba(...), ...
-rot [int]: Set the rotation angle for the gradient. (Default: 0)
-nograd: Use solid background color (primary) instead of gradient.
-nostyle: Do not print the default CSS file.
-includecss: Include CSS in html file.
-s [string]: Use single-file mode, followed by filename
Note: this simply sets both input/output folder to '.'
Changelog:
v23-01-2020 -- added check for white secondary color + fixed bugs
v22-01-2020 -- added includeCSS option + single file parsing + fixed links/brackets in a line + check
v21-01-2020 -- added check for missing format identifiers
v20-01-2020 -- some html changes
v17-01-2020 -- added text formatting in lists
v16-01-2020 -- added TOC auto-gen, tables, style configuration + example content + more
v15-01-2020 -- added header menu, fixed font styling, images, links
v14-01-2020 -- added font styling + code block + lists
v13-01-2020 -- initial
Needed files in your PATH:
grep
Please re-run script without help keyword