diff options
author | Evan Read <eread@gitlab.com> | 2018-12-18 06:43:34 +0300 |
---|---|---|
committer | GitLab Release Tools Bot <robert+release-tools@gitlab.com> | 2018-12-18 22:40:46 +0300 |
commit | 16e645934b5ccde17cf6872975fca96c6e7a2b6b (patch) | |
tree | df759157eeb9dbd9372d0c4f403b6f9454c9bc6c /doc | |
parent | cc2211295ee7a45906878fac728ab2bc1b26d591 (diff) |
Merge branch 'docs/frontmatter-delimiters' into 'master'
Add docs for frontmatter delimiters
See merge request gitlab-org/gitlab-ce!23876
(cherry picked from commit 662e55d78b8df8c796cb7f6fcc9be93d515df43d)
3602d2ab Add docs for frontmatter delimiters
75caf10e Edits to Front Matter section
Diffstat (limited to 'doc')
-rw-r--r-- | doc/user/markdown.md | 77 |
1 files changed, 68 insertions, 9 deletions
diff --git a/doc/user/markdown.md b/doc/user/markdown.md index debebd4c081..893658290e5 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -5,11 +5,11 @@ It is not valid for the [GitLab documentation website](https://docs.gitlab.com) nor [GitLab's main website](https://about.gitlab.com), as they both use [Kramdown](https://kramdown.gettalong.org) as their markdown engine. The documentation website uses an extended Kramdown gem, [GitLab Kramdown](https://gitlab.com/gitlab-org/gitlab_kramdown). -Consult the [GitLab Kramdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/) for a complete Kramdown reference._ +Consult the [GitLab Kramdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/) for a complete Kramdown reference. ## GitLab Flavored Markdown (GFM) -GitLab uses "GitLab Flavored Markdown" (GFM). It extends the [CommonMark specification][commonmark-spec] (which is based on standard Markdown) in a few significant ways to add some useful functionality. It was inspired by [GitHub Flavored Markdown](https://help.github.com/articles/basic-writing-and-formatting-syntax/). +GitLab uses "GitLab Flavored Markdown" (GFM). It extends the [CommonMark specification][commonmark-spec] (which is based on standard Markdown) in a few significant ways to add additional useful functionality. It was inspired by [GitHub Flavored Markdown](https://help.github.com/articles/basic-writing-and-formatting-syntax/). You can use GFM in the following areas: @@ -26,8 +26,7 @@ dependency to do so. Please see the [`github-markup` gem readme](https://github. > **Notes:** > -> For the best result, we encourage you to check this document out as [rendered -> by GitLab itself](markdown.md). +> We encourage you to view this document as [rendered by GitLab itself](markdown.md). > > As of 11.1, GitLab uses the [CommonMark Ruby Library][commonmarker] for Markdown processing of all new issues, merge requests, comments, and other Markdown content @@ -142,7 +141,7 @@ GFM will autolink almost any URL you copy and paste into your text: * <a href="irc://irc.freenode.net/gitlab">irc://irc.freenode.net/gitlab</a> * http://localhost:3000 -### Multiline Blockquote +### Multiline blockquote > If this is not rendered correctly, see https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#multiline-blockquote @@ -172,7 +171,7 @@ you can quote that without having to manually prepend `>` to every line! <p>you can quote that without having to manually prepend <code>></code> to every line!</p> </blockquote> -### Code and Syntax Highlighting +### Code and syntax highlighting > If this is not rendered correctly, see https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#code-and-syntax-highlighting @@ -242,7 +241,7 @@ s = "There is no highlighting for this." But let's throw in a <b>tag</b>. ``` -### Inline Diff +### Inline diff > If this is not rendered correctly, see https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#inline-diff @@ -309,7 +308,7 @@ On Linux, you can download [Noto Color Emoji](https://www.google.com/get/noto/he Ubuntu 18.04 (like many modern Linux distros) has this font installed by default. -### Special GitLab References +### Special GitLab references GFM recognizes special references. @@ -363,7 +362,7 @@ It also has a shorthand version to reference other projects from the same namesp | `project@9ba12248...b19a04f5` | commit range comparison | | `project~"Some label"` | issues with given label | -### Task Lists +### Task lists > If this is not rendered correctly, see https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#task-lists @@ -505,6 +504,66 @@ Becomes: For details see the [Mermaid official page][mermaid]. +### Front matter + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/23331) + in GitLab 11.6. + +Front matter is metadata included at the beginning of a markdown document, preceding +its content. This data can be used by static site generators such as [Jekyll](https://jekyllrb.com/docs/front-matter/) and [Hugo](https://gohugo.io/content-management/front-matter/), +and many other applications. + +In GitLab, front matter is only used in Markdown files and wiki pages, not the other places where Markdown formatting is supported. +When you view a Markdown file rendered by GitLab, any front matter is displayed as-is, in a box at the top of the document, before the rendered HTML content. +To view an example, you can toggle between the source and rendered version of a [GitLab documentation file](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/README.md). + +The following delimeters are supported: + +- YAML (`---`): + + ``` + --- + title: About Front Matter + example: + language: yaml + --- + ``` + +- TOML (`+++`): + + ``` + +++ + title = "About Front Matter" + [example] + language = "toml" + +++ + ``` + +- JSON (`;;;`): + + ``` + ;;; + { + "title": "About Front Matter" + "example": { + "language": "json" + } + } + ;;; + ``` + +Other languages are supported by adding a specifier to any of the existing +delimiters. For example: + +``` +---php +$title = "About Front Matter"; +$example = array( + 'language' => "php", +); +--- +``` + ## Standard Markdown ### Headers |