Template CSS test-ground and features overview
This document contains instructions on how to use pandoc templates to convert Markdown sources into an HTML document.
For a detailed preview of the tutorial template features, see:
Some of the tutorials contained in The PureBASIC Archives are written in GitHub flavored Markdown (GFM) and then converted into an HTML file. The markdown files constitute the source version of the tutorials, intended for developers and maintainers, while the HTML files are the “compiled” version of the tutorials, intended for actual end-users usage.
Source files in Markdown simplify maintaining the tutorials documentation and converting it to various formats. The final HTML version of the tutorial files offers a better reading experience, with proper formatting and advanced styling.
Conversion from one format to another is automated via scripts and handled by pandoc, a powerful command line tool for converting from one markup format to another. Pandoc is free, open source and cross platform:
The tutorial.template.html
file is a customized pandoc html5 template created specifically for The PureBASIC Archives. Pandoc uses this template to paginate converted tutorials into standalone html documents. For more information about pandoc template visit:
Conversion of a Markdown source document is carried out via the md2html.bat
batch script foun in:
This script has to be invoked via a custom script saved in the same folder of the tutorial source files. This custom script must set some enviroment variables with information about the source documents, and then invoke the conversion script which will make use of those variables to carry out conversion.
We will use here, as a reference, the FASM tutorial by TAJGA, located in:
The final html “compiled” tutorial is the tajga-fasm-tutorial.html
file, found inside the folder just mentioned. It’s markdown source files, and the custom script for its conversion are found in the /md-src/
subfolder. This separation of source files and html output is an arbitrary arrangement for keeping end-user folders uncluttered — ie: the final user will spend most of the time reading the final HTML documents, uninterested in the source files.
There are 3 source files to a tutorial document:
<filename>.md
— the main body of the tutorial.<filename>.before_body.md
— a brief summary placed before the TOC.<filename>.yaml
— a configuration file containing document related variables.Where <filename>
will be the whatever your document filename is going to be.
Markdown sources are in GitHub flavored markdown (GFM).
<filename>
followed by different extensions. You must following strictly the naming convention, and use consistent letter casing across filenames.The conversion script will “stitch” these files together into a single outuput HTML file, and use the variables defined in the YAML file to fill in various aspects of the template.
The reason why there are two markdown document files to a single tutorial is due to pandoc autogenerating a Table Of Contents on top of the main body of the tutorial. Since we usually want to put a title (and maybe a subtitle), a few lines of introduction (an abstract), mention the author(s), provide credits, a backlink and some copyright info on top of the final document — and before the TOC! — a second markdown document is needed for this: the <filename>.before_body.md
, which will not be indexed in the TOC.
When reprinting a tutorial found elsewhere, usually <filename>.md
will contain the contents of the original document, while <filename>.before_body.md
will contain all the legal stuff and references to the original article. Therefore this system of splitted files provides a convenient separation of original contents and added introductory remarks, and it’s also useful when reusing the same article in other contexts (which might require to include only the main body and add different headers to it).
In terms of what the user will see in the document, this is how the template will render the final document.
title
var inside the YAML file.subtitle
var inside the YAML file.<filename>.before_body.md
<filename>.md
<h1>
header in your *.before_body.md
file. But if you do so, you might want to avoid defining a title variable in the YAML file, to disable title generation from the YAML variable.The YAML file associated with the source document, beside defining the tutorial title and subtitle, can also contain extra variables used to fill in metadata in the <head>
section of the HTML document.
TO BE CONTINUED…
COMING SOON…
GitHub Flavored Markdown (GFM) is a variation on standard Markdown syntax, with some additional features. Pandoc conversion doesn’t support all GFM features — for example, you can’t use task-lists and emoji in your markdown sources. Some other features support might be determined by the settings used by our script invoking pandoc.
For both general and detailed information about Markdown syntax, please refer to the following links:
A brief resume of Markdown syntax shall be provided here, along with extra features supported by the templating system.
All classic Markdown inline styles are supported:
*
italic*
(or _
italic_
)**
bold**
(or __
bold__
)With the addition of:
~~
~~
.Some raw html tags can be used along with markdown source.
You can enlcose text within <mark>
tags to highlight it</mark>
.
Enclose within <kbd>
tags keystrokes that the user needs to press on his keyboard: <kbd>
Ctrl</kbd>
:
Press <kbd>Ctrl</kbd><kbd>C</kbd> to copy selected text.
the keystrokes will be rendered in a fashion resembling actual keyboard keys:
Press CtrlC to copy selected text.
Alerts are boxed contents intended to catch the user’s attention.
NOTE: This is a basic alert box, intended for Notes.
Markdown contents is wrapped in a<div class="alert">
.TIP: This is an info alert box, intended for Information notes, Tips, ecc.
Markdown contents is wrapped in a<div class="alert alert-info">
.WARNING: This is a warning alert box.
Markdown contents is wrapped in a<div class="alert alert-warn">
.WRONG: This is an error alert box to warn users about anything that is wrong, negative, risky, ecc.
Markdown contents is wrapped in a<div class="alert alert-error">
.RIGHT: This is a success alert box to warn users about anything that is positive, correct, working, ecc.
Markdown contents is wrapped in a<div class="alert alert-success">
.They are based on GitHub’s Primer’s primer-alerts (classes renamed from .flash*
to .alert*
, and some changes made):
Different kind of alert are avalaible by enclosing text in <div class="alert">
tags.
The basic alert is colored in gray, and is intended for general notes:
<div class="alert">
__NOTE__: This is a basic alert box, intended for __Notes__. Markdown contents is wrapped in a `<div class="alert">`.
</div>
renders to:
<div class="alert">
.Variations in color are available by adding an additional class to the <div>
element.
Intended for Info boxes. Use with <div class="alert alert-info">
:
<div class="alert alert-info">
__TIP__: This is an info alert box, intended for __Information__ notes.
</div>
renders to:
Warning alerts are in yellow. Use <div class="alert alert-warn">
:
<div class="alert alert-warn">
__WARNING__: This is a warning alert box.
</div>
renders to:
Error alerts are in red. Use <div class="alert alert-error">
:
<div class="alert alert-error">
__WRONG__: This is an error alert box, intended for warning the user about "DON'Ts", "CONs", wrong approaches, to show wrong syntaxes, error reports, ecc.
</div>
renders to:
Success alerts are in green. Use <div class="alert alert-success">
:
<div class="alert alert-success">
__RIGHT__: This is a success alert box, intended for warning user about "DOs", "PROs", correct approaches, to show right syntaxes, success reports, ecc.
</div>
renders to: