Skip to content

markup-format.md

Latest commit

 

History

History
351 lines (245 loc) · 11.1 KB

markup-format.md

File metadata and controls

351 lines (245 loc) · 11.1 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 file they're in. That way, they work in the docs and on GitHub and locally in a cloned repository. Link to the specific .md file, for example: [available services](../docs/src/configuration/services/_index.md).

If you are linking from a file for reuse, link relative to the src directory and start with /. For example: [available services](/configuration/services/_index.md).

Both of these ways help 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.

Links to headers

To link to a header, use # plus the lowercase heading name. Special characters are removed and spaces replaced by hyphens. So to link to a heading with the text Code & Style on the same page, use [link-text](#code--style).

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.

Footnotes

To add a footnote, add two parts:

  1. Mark the spot in the text where you want to add a note:

    This text will have a note.[^<FOOTNOTE_NAME>]

    The name can be anything as long as it's unique within the document. Don't use numbers as the notes are numbered automatically.

  2. Add the note at the end of the document:

    [^<FOOTNOTE_NAME>]: Here is the note about the text above.

    To have multiple paragraphs in the note, align them with four spaces at the start:

    [^<FOOTNOTE_NAME>]:
    This is the first paragraph.

    This is the second paragraph.

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 block location

If it's helpful to note where the code should be placed (such as in a .platform.app.yaml file), note that as an attribute of that block and it will appear in a tab:

```yaml {location=".platform.app.yaml"}
relationships:
    database: 'mysqldb:db

Refer to the UI and keys

When referring to text in the UI, use bold:

Click **Redeploy**.

To refer to buttons in the UI that use icons, use the icon shortcode with the alternative text for the button:

To share a log, open the log and click {{< icon share >}} **Copy URL**.

To refer to keys users should use on their keyboards, use <kbd> tags:

To select multiple lines, hold <kbd>Shift</kbd>.

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.

Reuse content

To reuse Markdown content in multiple places, use transclusion to include it.

  1. Create a new .md file in the docs/layouts/shortcodes directory. Make sure the context is clear from the name, for example reuse_markdown.md.

  2. Fill it with the content you want to repeat.

  3. Include the file in the other locations like so:

    {{% reuse_markdown %}}

Note that if your files have HTML characters (<, >, &, ', and ") inside a code block, the characters are escaped (appear as &lt; and so on). Avoid this problem by writing HTML files (reuse_html.html) instead of Markdown files and including them like so:

{{< reuse_html >}}

Variables in the file

You can pass variables to the file:

{{% reuse_markdown FileName="1" %}}

Use the variable in the file:

The file's name is: {{ .Get "FileName" }}

Inner content

For longer content specific to each file, you can put content inside the shortcode:

{{% reuse_markdown %}}

This is longer content that only appears for the file it's in
and not all files that use the shortcode.

{{% /reuse_markdown %}}

Use the inner content in the file:

Here is some content before the inner content.

{{ .Inner | .Page.RenderString }}

Here is some content after the inner content.

Static files

For static files that have already been created, 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" >}}
{{< readFile file="src/registry/images/examples/full/elasticsearch.app.yaml" highlight="yaml" location=".platform.app.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.
location Optional. To mark where the included code should be placed, for example .platform.app.yaml.