tajmone
commented
6 years ago One further consideration: deciding if we're going to use or not YAML headers in READMEs is a crucial decision at this point because it affects auto-generated pandoc variables.
If we're going to use auto-generated vars for the <title>, this means that the template var will have to calculated in the PB code and passed to pandoc via CLI options. Variables defined via CLI options can't be overriden by YAML headers because options have a higher priority over in-document defined vars.
Of course, we could use YAML headers just for the description and keywords vars, and let the app handle the category title automatically. This is fine, but this would be the right time to discuss it and decide a course of action regarding this — there might be some other pros and cons to consider in each approach.
SicroAtGit
Now I've added the
meta.yamlfile in "/_assets/" which contains commonly shared template metadata/vars as:header-title— for the tile in the website headerheader-subtitle— for the subtitle in the website headerdescription— string for<meta name="description" ...>, useful for SEOkeywords— list of keywords for HTML doc meta (good for SEO).This file allows separation between the template and fixed contents like Header's title and subtitle, so they can be tweaked without having to edit pandoc's HTML5 template.
These vars will be used for every page. But any section can override these variables by adding a YAML header to the
README.mdfile.For example, see the Gadget category page, where the
header-titlehas been overriden with a custom value by adding at the beginning ofREADME.mdfile:GitHub supports YAML headers in markdown files, and in the WebUI document preview the YAML variables are formatted in a special way, as you can see at this link:
... YAML vars are rendered as tables:
... which is pretty cool as far as previewing READMEs on GitHub website goes.
Of course, handling variables in YAML headers is very practical and allows to fine-tune some aspects of the template on a per-category base without the limitations of auto-generated values.
The downside is that many markdown editors don't handle well YAML headings, so editing the
README.mdfiles might become problematic in some editors (and often break HTML previews, live or otherwise).I wanted to ask you what you think about this. Strictly speaking, we don't need to use YAML headers to handle the document appearance, but having them would improve Search-Engines Optimization as it would allow to define custom values for
descriptionandkeywords— this would affect not only how search engines index the various categories, but also how they are shown to the user in the results page.Personally, I think that SEO is an important point (after all, the GitHub Pages website will be indexed, and some people might discover the project via Googling). This would allow to add the right keywords for each category and customize the description that will appear in Google search results. As far as local usage of the project goes, none of this really matters, of course.
Besides, there are Markdown editors that support YAML headers in markdown docs without breaking things (I use Sublime Text, and don't have problems).
But if you (or the other maintainers) use a specific editor for the project, and it doesn't handle YAML headers, then YAML headers might introduce some complications in the project's maintainance.