The Jekyll software makes use of Front Matter when generating the static HTML. This is the section at the top of the markdown files that starts and finishes with three hyphens.
Here is the Front Matter for this Contributing guide’s main page:
--- title: Contributing to Azure Citadel date: 2019-01-10 author: Richard Cheney tags: [citadel, markdown] comments: true header: overlay_image: /images/site/main.png teaser: /images/teaser/cloud-tools.png excerpt: Want to contribute content to Azure Citadel? Read our guide. hidden: true published: true sidebar: nav: "contributing" permalink: /contributing/ ---
Key defaults for the pages:
|read_time||true||boolean||Estimates the time to read, based on 100 words per minute|
|share||true||boolean||Show the “Share On” buttons for Twitter, Facebook and LinkedIn|
|comments||true||boolean||Whether to allow Disqus comments at the bottom of the page|
|toc||true||boolean||Show the table of contents on the right|
|toc_sticky||true||boolean||Keep the table of contents visible after scrolling|
|toc_depth||2||integer||Number of header levels to include in the table of contents|
Normally your Front Matter will also include a category. This should be a single value matching the directory, e.g. a file called
/devops/my-guide.md would have
category: devops, and therefore appear in the DevOps category page.
Jekyll will take that my-guide.md and generate a page available at
https://azurecitadel.com/devops/my-guide. (It actually creates an index.html within the my-guide folder in order to provide this “pretty” link.)
Permalinks can also be used to hardcode the generated pathing. In general, the use of permalink in pull requests will be discouraged. (These Contributing files are an exception as the generated pages are within
https://azurecitadel.com/contributing/ but they are located in
You cannot use the older categories array, which used to allow content in multiple categories.
Titles, excerpts and banner images
The title will go across the banner, which is plain blue by default.
You can customise the image by using the header:overlay_image and then path to one of the larger images in either /images/site or /images/header. If you wish to add your own then it should go into /images/header. Check the readme file for current guidance on the image files.
If you specify an excerpt then this will be the additional text that goes across the page header underneath the title.
The date field is pretty self explanatory, and always required.
Note that the date is used on the grid pages to determine order, but the date should not be updated to “bump” content up when there are only minor changes or fixes. Only change the date if there is a significant content update. We will normally use this to dictate if there should be a news post update, so if it isn’t newsworthy, it should retain the original date.
Note that future dates are permitted. This can be useful to release content at the same time as a service goes GA.
If you are running Jekyll locally on your machine (see reviewing), then you can use the
--future switch to generate the content locally for reviewing purposes.
Specify tags as an array. No more than four tags are allowed. Keep to lower case and hyphenate where there are multiple words, e.g. cognitive-services.
Check the Tags page and use existing tags where possible. New tags will be inevitable, but if there is an existing synonym then use that. E.g. use security-center, rather than creating azure-security-center or security-centre.
Please do not use tags that are already in the title of the lab as that will already be included in the search.
The following are not required but can be used to control visibility:
published: true hidden: false
Use published to control whether the page will be generated on the main site. This is useful for controlling the release of work in progress content.
You can use the
--unpublished switch when running Jekyll locally to see content that has
published: false set.
The hidden boolean dictates whether content will be listed on a category page. The markdown file for the contributing main page is
/prereqs/contributing.md, and would normally show in the pre-reqs category.
The header:teaser: value should path to a valid teaser image within /images/teaser. These are the smaller images used on the main page and the category pages.
Check the readme file for current guidance on the images.
You can create custom navigation to go across multiple pages and external links. These pages have one on the left, denoted by:
sidebar: nav: "contributing"
More on these when you get to multi page labs.
In the meantime, here is a quick guide to markdown.