Skip to content

Latest commit

 

History

History
223 lines (159 loc) · 7.75 KB

markup-format.md

File metadata and controls

223 lines (159 loc) · 7.75 KB

Markup reference for Platform.sh docs

Table of contents

Markdown

These docs are written in Markdown with GitHub Flavored Markdown syntax supported. It also supports definition lists, footnotes, and smart typography. Plus the modifications noted below.

It's rendered by the Goldmark parser.

Front matter

All pages should start with front matter. The following table presents the available options:

Item Type Description
title string The title that appears as an <h1> element at the top of the page.
sidebarTItle string An optional short version of the title to appear in the navigation sidebar.
weight integer Defines the order in which the page should appear in the sidebar. Higher numbers are lower.
toc Boolean Optionally allows you to hide the table of contents on a page (by setting to false).
layout single or list Set to single on _index.md files to give them the same layout as other pages.
aliases list of strings Optionally creates redirects to the page from the given locations. Start with / for root-relative locations. Start with ../ for locations relative to the current page.
description string Appears on list pages as a description of the page's content. Also overrides generic content for the <meta name="description"> tag for SEO. Can be used in the page with the description shortcode.

Headings

Because the title of a page should come from the front matter, top-level headings in the document should be H2 (##). You can add sub-headings at the next lower level, just be sure not to skip any levels.

Headings should be in sentence case (only the first word capitalized).

Line wrapping

For the reasons outlined at the Semantic Line Breaks website, you're encouraged to break Markdown lines at semantic breaks in paragraphs. This means adding a line break at the ends of sentences and at other semantic boundaries.

So instead of writing this:

Long paragraphs without breaks are hard to read. Breaking in semantic ways helps increase comprehension and also makes it easier to track changes in version control systems.

You can write this:

Long paragraphs without breaks are hard to read.
Breaking in semantic ways helps increase comprehension
and also makes it easier to track changes in version control systems.

Links

Always use inline links (in the format: [link text](link-location)). Remember to use meaningful link text.

Internal links (links to other docs pages) should be relative to the src directory and start with /. Link to the specific .md file, for example: [available services](/configuration/services/_index.md#type).

This helps prevent broken links in the docs by putting them through a check to see if the page exists. If the page doesn't exist, the build fails.

The check is done in a template with a render hook. See the Hugo docs on render hooks and the relref function that does the check.

Notes

To add extra information or a warning that stands outside the normal text flow, add a note. By default, a title of Note: is added.

{{< note >}}

A short note.

{{< /note }}

This shortcode accepts two optional parameters:

  • theme: Determines the color and the default title. The default theme is primary and may be set to info, or warning.
  • title: Sets the title of the note. The default is the theme with the first letter capitalized and a colon (Note:). To have no title, set this to none.
{{< note theme="warning" title="Danger, Will Robinson" >}}

Be careful!

{{< /note >}}

See the content guidelines for notes.

Images

You can add images using the standard Markdown syntax, except it is not possible to add titles.

Instead of titles, you can pass scaling values on a scale of 0 to 1 to set a maximum width on the image (every 0.1 = 10rem) and make it displayed inline.

<!-- Normal image syntax -->
![Description of image](/images/current_image.png)

<!-- Scaled image -->
![Description of image](/images/current_image.png "0.5")

<!-- Scaled image displayed inline, such as an icon in a sentence -->
![Description of image](/images/current_image.png "0.1-inline")

Remember to use alternative text when appropriate.

Videos & asciinema

You can add videos and asciinema recordings with shortcodes:

<!-- Video -->
{{< video src="videos/management-console/new-project-creation.mp4" >}}

<!-- Asciinema -->
{{< asciinema src="videos/asciinema/verify-cli-extended.cast" >}}

Code

Inline code statements, file names, and YAML keys should use backticks like this.

Longer code samples should be denoted with triple backticks before and after, with no extra whitespace between the backticks and the code block. Always specify the language of the code block. See the highlight.js docs for available language options.

Indentation

In YAML files, use 4 spaces to indent lines:

web:
    locations:
        '/': !include
            type: yaml
            path: 'main.yaml'

Keep the top-level key visible so readers can understand the code in context. (For example, don't leave out web: in the example above.)

Code tabs

Display code examples in multiple languages with code tabs. Tabs are divided by <---> and can each have different properties.

{{< codetabs >}}

---
title=Elasticsearch
file=static/files/fetch/examples/php/elasticsearch
highlight=php
---

<--->

---
title=Memcached
file=none
highlight=python
---

from jwcrypto import jws, jwk

{{< /codetabs >}}
Property Description
title The title that appears on the tab.
highlight The language to use for highlighting, as in code blocks. If set to false, content renders as Markdown.
file If not set to none, the displayed code comes from the specified local file.

Reusing content

To reuse content in multiple places, you can save it as a shortcode and then use transclusion to include it elsewhere. For this, use the readFile shortcode.

{{< readFile file="src/registry/images/tables/runtimes_supported.md" markdownify="true">}}
{{< readFile file="src/registry/images/examples/full/php.app.yaml" highlight="yaml" >}}
Property Description
file The location of the file to include relative to the docs root.
markdownify Optional. For when you are using a .md file and want to include markdown.
highlight Optional. For when you're including code examples. The language to use for highlighting, as in code blocks.