-
Notifications
You must be signed in to change notification settings - Fork 2
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Refactor Markdown directives for updated syntax compatibility (#199)
Co-authored-by: Jan Calanog <[email protected]>
- Loading branch information
Showing
24 changed files
with
209 additions
and
131 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,5 +1,5 @@ | ||
This is a snippet included on "{{page_title}}". | ||
|
||
```{tip} | ||
:::{tip} | ||
This is a snippet | ||
``` | ||
::: |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,72 @@ | ||
--- | ||
title: Markdown Syntax Extensions | ||
title_navigation: Markdown Syntax | ||
--- | ||
|
||
## Syntax | ||
|
||
The new documentation fully supports [CommonMark](https://commonmark.org/) Markdown syntax. | ||
|
||
On top of this widely accepted feature set we have various extensions points. | ||
|
||
## Directives | ||
|
||
Directives are our main extension point over markdown and follows the following syntax | ||
|
||
|
||
```markdown | ||
:::{EXTENSION} ARGUMENTS | ||
:OPTION: VALUE | ||
|
||
Nested content that will be parsed as markdown | ||
::: | ||
``` | ||
|
||
- `EXTENSION` is the name of the directive e.g [`note`](admonitions.md#note) | ||
- `ARGUMENT` some directives take a main argumnt e.g [`:::{include} _snippets/include.md`](file_inclusion.md) | ||
- `OPTION` and `VALUE` can be used to further customize a given directive. | ||
|
||
The usage of `:::` allows the nested markdown to be syntax highlighted properly by editors and web viewers. | ||
|
||
Our (directives) are always wrapped in brackets `{ }`. | ||
|
||
### Nesting Directives | ||
|
||
You can increase the leading semicolons to include nested directives. Here the `{note}` wraps a `{hint}`. | ||
|
||
```markdown | ||
::::{note} My note | ||
:::{hint} My hint | ||
Content displayed in the hint admonition | ||
::: | ||
Content displayed in the note admonition | ||
:::: | ||
``` | ||
|
||
## Literal directives | ||
|
||
For best editor compatability it is recommended to use triple backticks for content that needs to be displayed literally | ||
|
||
````markdown | ||
```js | ||
const x = 1; | ||
``` | ||
```` | ||
|
||
Many markdown editors support syntax highlighting for embedded code blocks. | ||
|
||
## Github Flavored Markdown | ||
|
||
We support some of GitHub flavor markdown extensions these are highlighted in green here: https://github.github.com/gfm/ | ||
|
||
Supported: | ||
|
||
* GFM Tables [](tables.md#github-flavored-markdown-gfm-table) | ||
* Strikethrough ~~as seen here~~ | ||
|
||
Not supported: | ||
|
||
* Task lists | ||
* Auto links (http://www.elastic.co) | ||
* Using a subset of html | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -2,6 +2,6 @@ | |
title: Sidebars | ||
--- | ||
|
||
```{warning} | ||
:::{warning} | ||
This feature is not currently supported in Elastic Docs V3. | ||
``` | ||
::: |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.