how to use it for convert markdown to html?

[tajmone]

how to use it for convert markdown to html?

[tajmone]

I want to know how to use, give a user tutorial.

You're right, I should provide some clear usage instructions. I've added it to enhancements list. Sorry for that, I get to work on it on spare time and don't always get to accomplish as much as I'd love to.

Because I test it, but never get a good html.

There seem to be different issues going on at the same time with your usage.

The Title Warning

As for the warning you get, this is somethig you always get if you don't specify a title for the document:

[WARNING] This document format requires a nonempty <title> element.
Please specify either 'title' or 'pagetitle' in the metadata.
Falling back to 'openapi'

You can just ignore it, it's not an error but a warning and a reminder.

If you need to specify a title, you can either add it via a YAML header into the source markdown document, or define it on the command line via template variables option:

--metadata=title:"Your Title"

NOTE: There seems to be a bug in pandoc right now, because even when I provide the title via the above option, I still get the warning, even if the title actually show up in the final document. I'll open an issue for this bug.

Installing The Template

First of all, the template is intended as a standalone HTML5 template. The final template file is GitHub.html5, and it should be "installed" (copied) to pandoc's data folder (which on Windows would be %APPDATA%\Pandoc\templates\).

The batch script INSTALL.bat will take care of copying/updating the GitHub.html5 to pandoc's data folder, so you should run the script to make the GitHub template available to pandoc system-wide.

On Linux, pandoc' data dir will be $HOME/.pandoc, so the template file should be copied to ~/.pandoc/templates

You can find the default user data directory on your system by looking at the output of pandoc --version.

• http://pandoc.org/MANUAL.html#general-options

Using The Template

The intended way to use the GtiHub template is via the --template= option. Example:

pandoc openapi.md -o openapi.html --template=GitHub.html5 --self-contained

... pandoc will look for the template in the template folder (of pandoc's data dir) and use it for the conversion to HTML5 of your document.

You are currently trying to use just the css file of the template:

pandoc openapi.md -o openapi.html --css GitHub.css --self-contained

You've taken GitHub.css from the src folder, which contains the source files used to build the final template. The intended use for the template is that of a fully standalone HTML5 template, with the css stylesheet incorporated into it, so that a single-file document can be produced.

If you look at the README file in templates/html5/github/src/, and peek around the source files, you'll notice that the css file is ultimately injected into the HTML template. Keeping the css file external to the template won't work because the converted document wouldn't be able to locate it when using the template from pandoc's data dir; this is the reason I've incorporated it in the template.

For more info on templates, see:

• http://pandoc.org/MANUAL.html#templates

Using The CSS Only

Of course, nothing prevents you from using the GitHub.css stylesheet without the template. But because it's designed to go with it's HTML template, you won't get good results because some classes won't be covered in pandoc's default HTML5 template.

[tajmone]

Opened an issue for the title warning showing up even when the title is defined via -V:

jgm/pandoc#4449

[tajmone]

@wenjuanhenxing , I've now added some installation and usage instructions for the template:

https://github.com/tajmone/pandoc-goodies/tree/master/templates/html5/github#installation

If you think these instructions are sufficient, you can just close this issue. If not, tell me what could/should be added to make them more exhaustive.

[wenjuanhenxing]

get，I succeeded in the experiment.
Thank you very much.