Skip to content

Commit

Permalink
Refactor Markdown directives for updated syntax compatibility (#199)
Browse files Browse the repository at this point in the history
Co-authored-by: Jan Calanog <[email protected]>
  • Loading branch information
Mpdreamz and reakaleek authored Jan 14, 2025
1 parent 5b2d6e8 commit ddd64a5
Show file tree
Hide file tree
Showing 24 changed files with 209 additions and 131 deletions.
2 changes: 2 additions & 0 deletions docs/source/docset.yml
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ external_hosts:
- palletsprojects.com
- google.com
- checkvist.com
- commonmark.org
exclude:
- '_*.md'
subs:
Expand Down Expand Up @@ -64,6 +65,7 @@ toc:
- folder: syntax
children:
- file: index.md
- file: md-extensions.md
- file: admonitions.md
- file: automated_settings.md
- file: code.md
Expand Down
4 changes: 2 additions & 2 deletions docs/source/syntax/_snippets/reusable-snippet.md
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
```
:::
20 changes: 10 additions & 10 deletions docs/source/syntax/admonitions.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,9 +39,9 @@ This is a warning.
:::
```

```{warning}
:::{warning}
This is a warning.
```
:::

### Tip

Expand All @@ -53,9 +53,9 @@ This is a tip.
:::
```

```{tip}
:::{tip}
This is a tip.
```
:::

### Important

Expand All @@ -67,15 +67,15 @@ This is an important notice.
:::
```

```{important}
:::{important}
This is an important notice.
```
:::

## Collapsible admonitions

```{tip}
:::{tip}
Also see [dropdowns](./dropdowns.md).
```
:::

Use `:open: <bool>` to make an admonition collapsible.

Expand All @@ -89,13 +89,13 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor i
:::
```

```{note}
:::{note}
:open:

Longer content can be collapsed to take less space.

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
```
:::

---

Expand Down
4 changes: 2 additions & 2 deletions docs/source/syntax/automated_settings.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,5 +32,5 @@ groups:
_Everything below this line is auto-generated._
```{settings} /syntax/kibana-alerting-action-settings.yml
```
:::{settings} /syntax/kibana-alerting-action-settings.yml
:::
4 changes: 2 additions & 2 deletions docs/source/syntax/code.md
Original file line number Diff line number Diff line change
Expand Up @@ -74,9 +74,9 @@ var apiKey = new ApiKey("<API_KEY>"); // Set up the api key
var client = new ElasticsearchClient("<CLOUD_ID>", apiKey);
```

```{note}
:::{note}
the comments have the follow code to be hoisted as a callout.
```
:::

````markdown
```csharp
Expand Down
4 changes: 2 additions & 2 deletions docs/source/syntax/conditionals.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,6 @@
title: Conditionals
---

```{warning}
:::{warning}
This feature is not currently supported in Elastic Docs V3.
```
:::
4 changes: 2 additions & 2 deletions docs/source/syntax/dropdowns.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,10 +27,10 @@ Dropdown content
:::
```

```{dropdown} Dropdown Title
:::{dropdown} Dropdown Title
:open:
Dropdown content
```
:::

## Asciidoc syntax

Expand Down
4 changes: 2 additions & 2 deletions docs/source/syntax/example_blocks.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,6 @@
title: Example blocks
---

```{warning}
:::{warning}
This feature is not currently supported in Elastic Docs V3.
```
:::
8 changes: 4 additions & 4 deletions docs/source/syntax/images.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,9 +12,9 @@ Images can be referenced from the top-level `_static` dir or a local image dir.

Screenshots are images displayed with a box-shadow.

```{warning}
:::{warning}
This feature is not currently supported in Elastic Docs V3.
```
:::

## Block-level images

Expand All @@ -33,10 +33,10 @@ Or, use the `image` directive.
:::
```

```{image} /_static/img/observability.png
:::{image} /_static/img/observability.png
:alt: Elasticsearch
:width: 250px
```
:::

## Inline images

Expand Down
72 changes: 72 additions & 0 deletions docs/source/syntax/md-extensions.md
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

4 changes: 2 additions & 2 deletions docs/source/syntax/passthrough.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,6 @@
title: Passthrough blocks
---

```{warning}
:::{warning}
This feature is not currently supported in Elastic Docs V3.
```
:::
4 changes: 2 additions & 2 deletions docs/source/syntax/sidebars.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,6 @@
title: Sidebars
---

```{warning}
:::{warning}
This feature is not currently supported in Elastic Docs V3.
```
:::
12 changes: 7 additions & 5 deletions src/Elastic.Markdown/Myst/Directives/DirectiveBlockParser.cs
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ public DirectiveBlockParser()

private readonly string[] _codeBlocks = ["code", "code-block", "sourcecode"];

private readonly FrozenDictionary<string, int> _unsupportedBlocks = new Dictionary<string, int>
private static readonly FrozenDictionary<string, int> UnsupportedBlocks = new Dictionary<string, int>
{
{ "bibliography", 5 },
{ "blockquote", 6 },
Expand Down Expand Up @@ -63,17 +63,19 @@ public DirectiveBlockParser()
{ "seealso", 3 }
}.ToFrozenDictionary();

private static readonly FrozenDictionary<string, int>.AlternateLookup<ReadOnlySpan<char>> UnsupportedLookup =
UnsupportedBlocks.GetAlternateLookup<ReadOnlySpan<char>>();

protected override DirectiveBlock CreateFencedBlock(BlockProcessor processor)
{
var info = processor.Line.AsSpan();

if (processor.Context is not ParserContext context)
throw new Exception("Expected parser context to be of type ParserContext");

// TODO alternate lookup .NET 9
var directive = info.ToString().Trim(['{', '}', '`']);
if (_unsupportedBlocks.TryGetValue(directive, out var issueId))
return new UnsupportedDirectiveBlock(this, directive, issueId, context);
var directive = info.Trim(['{', '}', '`', ':']);
if (UnsupportedLookup.TryGetValue(directive, out var issueId))
return new UnsupportedDirectiveBlock(this, directive.ToString(), issueId, context);

if (info.IndexOf("{tab-set}") > 0)
return new TabSetBlock(this, context);
Expand Down
8 changes: 4 additions & 4 deletions tests/Elastic.Markdown.Tests/Directives/AdmonitionTests.cs
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,9 @@ namespace Elastic.Markdown.Tests.Directives;

public abstract class AdmonitionTests(ITestOutputHelper output, string directive) : DirectiveTest<AdmonitionBlock>(output,
$$"""
```{{{directive}}}
:::{{{directive}}}
This is an attention block
```
:::
A regular paragraph.
"""
)
Expand Down Expand Up @@ -65,10 +65,10 @@ A regular paragraph.

public class DropdownTitleTests(ITestOutputHelper output) : DirectiveTest<AdmonitionBlock>(output,
"""
```{dropdown} This is my custom dropdown
:::{dropdown} This is my custom dropdown
:open:
This is an attention block
```
:::
A regular paragraph.
"""
)
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -11,11 +11,11 @@ namespace Elastic.Markdown.Tests.Directives;
public abstract class AdmonitionUnsupportedTests(ITestOutputHelper output, string directive)
: DirectiveTest<UnsupportedDirectiveBlock>(output,
$$"""
```{{{directive}}}
This is an attention block
```
A regular paragraph.
"""
:::{{{directive}}}
This is an attention block
:::
A regular paragraph.
"""
)
{
[Fact]
Expand Down
4 changes: 2 additions & 2 deletions tests/Elastic.Markdown.Tests/Directives/AppliesBlockTests.cs
Original file line number Diff line number Diff line change
Expand Up @@ -12,9 +12,9 @@ namespace Elastic.Markdown.Tests.Directives;
public class AppliesBlockTests(ITestOutputHelper output) : DirectiveTest<AppliesBlock>(output,
"""
# heading
```{applies}
:::{applies}
:eck: unavailable
```
:::
"""
)
{
Expand Down
8 changes: 4 additions & 4 deletions tests/Elastic.Markdown.Tests/Directives/ImageTests.cs
Original file line number Diff line number Diff line change
Expand Up @@ -12,10 +12,10 @@ namespace Elastic.Markdown.Tests.Directives;

public class ImageBlockTests(ITestOutputHelper output) : DirectiveTest<ImageBlock>(output,
"""
```{image} img/observability.png
:::{image} img/observability.png
:alt: Elasticsearch
:width: 250px
```
:::
"""
)
{
Expand Down Expand Up @@ -43,13 +43,13 @@ public void ImageIsFoundSoNoErrorIsEmitted()

public class FigureTests(ITestOutputHelper output) : DirectiveTest<ImageBlock>(output,
"""
```{figure} https://github.com/rowanc1/pics/blob/main/sunset.png?raw=true
:::{figure} https://github.com/rowanc1/pics/blob/main/sunset.png?raw=true
:label: myFigure
:alt: Sunset at the beach
:align: center
Relaxing at the beach 🏝 🌊 😎
```
:::
"""
)
{
Expand Down
4 changes: 2 additions & 2 deletions tests/Elastic.Markdown.Tests/Directives/MermaidTests.cs
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ namespace Elastic.Markdown.Tests.Directives;

public class MermaidBlockTests(ITestOutputHelper output) : DirectiveTest<MermaidBlock>(output,
"""
```{mermaid} /_static/img/observability.png
:::{mermaid} /_static/img/observability.png
flowchart LR
A[Jupyter Notebook] --> C
B[MyST Markdown] --> C
Expand All @@ -21,7 +21,7 @@ B[MyST Markdown] --> C
D --> H[React]
D --> I[HTML]
D <--> J[JATS]
```
:::
"""
)
{
Expand Down
Loading

0 comments on commit ddd64a5

Please sign in to comment.