From aab5186199e62ac7a805dde9dc1fa26c2d0b42b0 Mon Sep 17 00:00:00 2001 From: bmorelli25 Date: Mon, 6 Jan 2025 09:22:31 -0800 Subject: [PATCH 1/6] update syntax guide --- docs/source/syntax/admonitions.md | 84 ++++++++++-------------- docs/source/syntax/automated_settings.md | 2 +- 2 files changed, 35 insertions(+), 51 deletions(-) diff --git a/docs/source/syntax/admonitions.md b/docs/source/syntax/admonitions.md index f8550b50..279ffe3a 100644 --- a/docs/source/syntax/admonitions.md +++ b/docs/source/syntax/admonitions.md @@ -7,21 +7,14 @@ Admonitions allow you to highlight important information with varying levels of ## Basic admonitions Admonitions can span multiple lines and support inline formatting. +Available admonition types include: -`````{tab-set} +- Note +- Warning +- Tip +- Important -````{tab-item} MD Syntax - -### Available admonition types - -- `note` -- `warning` -- `tip` -- `important` - -### Syntax - -**Note** +### Note A relevant piece of information with no serious repercussions if ignored. @@ -36,7 +29,7 @@ It can span multiple lines and supports inline formatting. This is a note. ::: -**Warning** +### Warning You could permanently lose data or leak sensitive information. @@ -50,7 +43,7 @@ This is a warning. This is a warning. ``` -**Tip** +### Tip Advice to help users make better choices when using a feature. @@ -64,7 +57,7 @@ This is a tip. This is a tip. ``` -**Important** +### Important Ignoring this information could impact performance or the stability of your system. @@ -78,43 +71,11 @@ This is an important notice. This is an important notice. ``` -```` - -````{tab-item} Asciidoc Syntax - -| **Asciidoc Type** | **When to use it** | -|--------------|-----------------------------------------------------------------------------------| -| **Warning** | You could permanently lose data or leak sensitive information. | -| **Important**| Ignoring the information could impact performance or the stability of your system.| -| **Note** | A relevant piece of information with no serious repercussions if ignored. | -| **Tip** | Advice to help you make better choices when using a feature. | - - -**Inline Admonition:** -```none -NOTE: This is a note. -It can be multiple lines, but not multiple paragraphs. -``` - -**Block Admonition:** - -```none -[WARNING] -======= -This is a warning. - -It can contain multiple paragraphs. -======= -::: -``` - -````` - ## Collapsible admonitions -You can use `:open: ` to make an admonition collapsible. +Use `:open: ` to make an admonition collapsible. -```none +```markdown :::{note} :open: @@ -131,3 +92,26 @@ 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. ``` + +--- + +## Asciidoc Syntax + +### Inline Admonition + +```markdown +NOTE: This is a note. +It can be multiple lines, but not multiple paragraphs. +``` + +### Block Admonition + +```markdown +[WARNING] +======= +This is a warning. + +It can contain multiple paragraphs. +======= +::: +``` diff --git a/docs/source/syntax/automated_settings.md b/docs/source/syntax/automated_settings.md index 22f59230..0eeeb616 100644 --- a/docs/source/syntax/automated_settings.md +++ b/docs/source/syntax/automated_settings.md @@ -6,7 +6,7 @@ Elastic Docs V3 supports the ability to build a markdown settings reference from ### Syntax -```none +```markdown :::{settings} /syntax/kibana-alerting-action-settings.yml ::: ``` From b0d6452f17e495c5f2f18632b0f2bb72667247d6 Mon Sep 17 00:00:00 2001 From: bmorelli25 Date: Mon, 6 Jan 2025 09:22:46 -0800 Subject: [PATCH 2/6] more --- docs/source/syntax/code.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/source/syntax/code.md b/docs/source/syntax/code.md index bef661fb..49584a14 100644 --- a/docs/source/syntax/code.md +++ b/docs/source/syntax/code.md @@ -22,7 +22,7 @@ project: ### Asciidoc syntax -```none +```markdown [source,sh] -------------------------------------------------- GET _tasks @@ -33,8 +33,8 @@ GET _tasks?nodes=nodeId1,nodeId2&actions=cluster:* ### Code blocks with callouts -A code block can include `<\d+>` at the end to indicate code callouts. -A code block with this style of callouts **needs** to be followed by an ordered list with an equal amount of items as called out. +A code block can include `<\d+>` at the end to indicate code callouts. +A code block with this style of callouts **needs** to be followed by an ordered list with an equal amount of items as called out. Otherwise, the docs-builder will throw an error. This syntax mimics what was implemented for our asciidoc system @@ -42,19 +42,19 @@ This syntax mimics what was implemented for our asciidoc system ````markdown ```yaml project: - title: MyST Markdown + title: MyST Markdown github: https://github.com/jupyter-book/mystmd license: code: MIT content: CC-BY-4.0 <1> - subject: MyST Markdown + subject: MyST Markdown ``` 1. The license ```` -### Magic Callout +### Magic Callout You can include the callouts also directly as code using either `//` or `#` comments. @@ -63,7 +63,7 @@ These will then be listed and numbered automatically ````markdown ```csharp var apiKey = new ApiKey(""); // Set up the api key -var client = new ElasticsearchClient("", apiKey); +var client = new ElasticsearchClient("", apiKey); ``` ```` @@ -71,10 +71,10 @@ Will output: ```csharp var apiKey = new ApiKey(""); // Set up the api key -var client = new ElasticsearchClient("", apiKey); +var client = new ElasticsearchClient("", apiKey); ``` -```{note} +```{note} the comments have the follow code to be hoisted as a callout. ``` @@ -82,7 +82,7 @@ the comments have the follow code to be hoisted as a callout. ```csharp // THIS IS NOT A CALLOUT var apiKey = new ApiKey(""); // However this is -var client = new ElasticsearchClient("", apiKey); +var client = new ElasticsearchClient("", apiKey); ``` ```` @@ -91,5 +91,5 @@ will output: ```csharp // THIS IS NOT A CALLOUT var apiKey = new ApiKey(""); // However this is -var client = new ElasticsearchClient("", apiKey); +var client = new ElasticsearchClient("", apiKey); ``` From cb10226daec5f37e1ffc55e20eaa77716e90ef9a Mon Sep 17 00:00:00 2001 From: bmorelli25 Date: Mon, 6 Jan 2025 10:38:57 -0800 Subject: [PATCH 3/6] various docs / syntax guide updates --- README.md | 8 +-- docs/source/syntax/admonitions.md | 4 ++ docs/source/syntax/dropdowns.md | 40 +++++++------- docs/source/syntax/frontmatter.md | 18 +++---- docs/source/syntax/images.md | 10 ++-- docs/source/syntax/links.md | 32 +++++++++++- docs/source/syntax/tables.md | 86 +++++++++++++++++++------------ 7 files changed, 124 insertions(+), 74 deletions(-) diff --git a/README.md b/README.md index 990b1ddb..0705a2f6 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# docs-builder. +# docs-builder You've reached the home of the latest incarnation of the documentation tooling. @@ -131,15 +131,17 @@ https://github.com/elastic/{your-repository}/settings/pages ## Run without docker -If you have dotnet 8 installed you can use its CLI to publish a self-contained `docs-builder` native code +You can use the .NET CLI to publish a self-contained `docs-builder` native code binary. (On my M2 Pro mac the binary is currently 13mb) +Install [.NET 9.0](https://dotnet.microsoft.com/en-us/download/dotnet/9.0), then run: + ```bash dotnet publish "src/docs-builder/docs-builder.csproj" -c Release -o .artifacts/publish \ --self-contained true /p:PublishTrimmed=true /p:PublishSingleFile=false /p:PublishAot=true -a arm64 ``` -**Note**: `-a` should be the machines CPU architecture +**Note**: `-a` should be the machine's CPU architecture The resulting binary `./.artifacts/publish/docs-builder` will run on machines without .NET installed diff --git a/docs/source/syntax/admonitions.md b/docs/source/syntax/admonitions.md index 279ffe3a..3f480eff 100644 --- a/docs/source/syntax/admonitions.md +++ b/docs/source/syntax/admonitions.md @@ -73,6 +73,10 @@ This is an important notice. ## Collapsible admonitions +```{tip} +Also see [dropdowns](./dropdowns.md). +``` + Use `:open: ` to make an admonition collapsible. ```markdown diff --git a/docs/source/syntax/dropdowns.md b/docs/source/syntax/dropdowns.md index 1b5068f8..54b6d917 100644 --- a/docs/source/syntax/dropdowns.md +++ b/docs/source/syntax/dropdowns.md @@ -2,11 +2,9 @@ title: Dropdowns --- -Dropdowns allow you to hide and reveal content on user interaction. +Dropdowns allow you to hide and reveal content on user interaction. By default, dropdowns are collapsed. This hides content until a user clicks the title of the collapsible block. -### Syntax - -By default, dropdowns are collapsed. This hides content until a user clicks the title of the collapsible block. +## Syntax ```markdown :::{dropdown} Dropdown Title @@ -18,7 +16,23 @@ Dropdown content Dropdown content ::: -### Asciidoc syntax +### Open by default + +You can specify that the dropdown content should be visible by default. Do this by specifying the `open` option. Users can collapse content by clicking on the dropdown title. + +```markdown +:::{dropdown} Dropdown Title +:open: +Dropdown content +::: +``` + +```{dropdown} Dropdown Title +:open: +Dropdown content +``` + +## Asciidoc syntax ```asciidoc .The `elasticsearch-setup-passwords` tool is deprecated. @@ -39,19 +53,3 @@ starting {es}, it will fail because the `elastic` user password is already configured. ==== ``` - -### Open by default - -You can also specify that the content should be visible by default, but can also be collapsed by the user. Do this by specifying the `open` option. - -```markdown -:::{dropdown} Dropdown Title -:open: -Dropdown content -::: -``` - -```{dropdown} Dropdown Title -:open: -Dropdown content -``` \ No newline at end of file diff --git a/docs/source/syntax/frontmatter.md b/docs/source/syntax/frontmatter.md index a536e0d6..8a8c5d68 100644 --- a/docs/source/syntax/frontmatter.md +++ b/docs/source/syntax/frontmatter.md @@ -4,16 +4,10 @@ title: Frontmatter Each MD file referenced in the TOC requires frontmatter. Frontmatter is YAML-formatted metadata about a page, at the beginning of each file. +Supported frontmatter includes: -## Title - -tbd - -[Title](./titles.md) link. - - -## Applies to - -tbd - -[Applies](./applies.md) link. \ No newline at end of file +| Frontmatter | Learn more | +| ------------------- | --------------------------- | +| `title` | See [title](./titles.md) | +| `navigation_title` | See [title](./titles.md) | +| `applies` | See [product availability](./applies.md) | diff --git a/docs/source/syntax/images.md b/docs/source/syntax/images.md index b6f20b0b..6f0de88f 100644 --- a/docs/source/syntax/images.md +++ b/docs/source/syntax/images.md @@ -2,18 +2,20 @@ title: Images --- -Images include screenshots, inline images, icons, and more. +Images include screenshots, inline images, icons, and more. Syntax for images is like the syntax for links, with two differences: +1. instead of link text, you provide an image description +2. an image description starts with `![` not just `[` Images can be referenced from the top-level `_static` dir or a local image dir. ## Screenshots +Screenshots are images displayed with a box-shadow. + ```{warning} This feature is not currently supported in Elastic Docs V3. ``` -Screenshots get a box-shadow. - ## Block-level images ```markdown @@ -36,7 +38,7 @@ Or, use the `image` directive. :width: 250px ``` -## Inline image +## Inline images ```markdown Here is the same image used inline ![Elasticsearch](/_static/img/observability.png) diff --git a/docs/source/syntax/links.md b/docs/source/syntax/links.md index f977453c..77947516 100644 --- a/docs/source/syntax/links.md +++ b/docs/source/syntax/links.md @@ -2,4 +2,34 @@ title: Links --- -tbd \ No newline at end of file +A link contains link text (the visible text) and a link destination (the URI that is the link destination). The link text can include inline elements. + +## Inline link + +``` +[Link title](links.html) +``` + +[Link title](links.html) + +``` +[**Hi**, _I'm md_](links.html) +``` + +[**Hi**, _I'm md_](links.html) + +## Anchor link + +You can link to a heading on a page with an anchor link. The link destination should be a `#` followed by the header text. Convert spaces to dashes (`-`). + +``` +I link to the [Inline link](#inline-link) heading above. +``` + +I link to the [Inline link](#inline-link) heading above. + +``` +I link to the [Notes](tables.html#notes) heading on the [Tables](tables.html) page. +``` + +I link to the [Notes](tables.html#notes) heading on the [Tables](tables.html) page. \ No newline at end of file diff --git a/docs/source/syntax/tables.md b/docs/source/syntax/tables.md index 46707553..0d10e117 100644 --- a/docs/source/syntax/tables.md +++ b/docs/source/syntax/tables.md @@ -2,48 +2,68 @@ title: Tables --- -## GFM Table +A table is an arrangement of data with rows and columns. Each row consists of cells containing arbitrary text in which inlines are parsed, separated by pipes `|`. The rows of a table consist of: -You can use the GFM (GitHub Flavored Markdown) table syntax to create a table. +* a single header row +* a delimiter row separating the header from the data +* zero or more data rows -| Country | Capital | -| ------- | --------------- | -| USA | Washington D.C. | -| Canada | Ottawa | +## Notes -## `{table}` Directive +* A leading and trailing pipe is recommended for clarity of reading +* Spaces between pipes and cell content are trimmed +* Block-level elements cannot be inserted in a table -You can use the `table` directive which gives you configuration captions such as caption and alignment. +## GitHub Flavored Markdown (GFM) Table -```{table} Countries and their capitals -:widths: auto -:align: center +You can use the GFM table syntax to create a table: +``` | Country | Capital | | ------- | --------------- | | USA | Washington D.C. | | Canada | Ottawa | ``` -## `{list-table}` Directive - -You can also use the `list-table` directive to create a table from data. - -```{list-table} Frozen Delights! -:widths: 15 10 30 -:header-rows: 1 - -* - Treat - - Quantity - - Description -* - Albatross - - 2.99 - - On a stick! -* - Crunchy Frog - - 1.49 - - If we took the bones out, it wouldn't be - crunchy, now would it? -* - Gannet Ripple - - 1.99 - - On a stick! -``` +| Country | Capital | +| ------- | --------------- | +| USA | Washington D.C. | +| Canada | Ottawa | + +% Neither of these work +% ## `{table}` Directive +% +% You can use the `table` directive which gives you configuration captions such as caption and alignment. +% +% ```{table} Countries and their capitals +% :widths: auto +% :align: right +% +% | Country | Capital | +% | ------- | --------------- | +% | USA | Washington D.C. | +% | Canada | Ottawa | +% ``` --> +% +%