Docs & Syntax guide updates (#129)

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
 

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,15 @@ 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.
+## Collapsible admonitions
 
-It can contain multiple paragraphs.
-=======
-:::
+```{tip}
+Also see [dropdowns](./dropdowns.md).
 ```
 
-`````
-
-## Collapsible admonitions
+Use `:open: <bool>` to make an admonition collapsible.
 
-You can use `:open: <bool>` to make an admonition collapsible.
-
-```none
+```markdown
 :::{note}
 :open:
 
@@ -131,3 +96,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.
+=======
+:::
+```

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
 :::
 ```

docs/source/syntax/code.md

@@ -22,7 +22,7 @@ project:
 
 ### Asciidoc syntax
 
-```none
+```markdown
 [source,sh]
 --------------------------------------------------
 GET _tasks
@@ -33,28 +33,28 @@ 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
 
 ````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,26 +63,26 @@ These will then be listed and numbered automatically
 ````markdown
 ```csharp
 var apiKey = new ApiKey("<API_KEY>"); // Set up the api key
-var client = new ElasticsearchClient("<CLOUD_ID>", apiKey); 
+var client = new ElasticsearchClient("<CLOUD_ID>", apiKey);
 ```
 ````
 
 Will output:
 
 ```csharp
 var apiKey = new ApiKey("<API_KEY>"); // Set up the api key
-var client = new ElasticsearchClient("<CLOUD_ID>", apiKey); 
+var client = new ElasticsearchClient("<CLOUD_ID>", apiKey);
 ```
 
-```{note} 
+```{note}
 the comments have the follow code to be hoisted as a callout.
 ```
 
 ````markdown
 ```csharp
 // THIS IS NOT A CALLOUT
 var apiKey = new ApiKey("<API_KEY>"); // However this is
-var client = new ElasticsearchClient("<CLOUD_ID>", apiKey); 
+var client = new ElasticsearchClient("<CLOUD_ID>", apiKey);
 ```
 ````
 
@@ -91,5 +91,5 @@ will output:
 ```csharp
 // THIS IS NOT A CALLOUT
 var apiKey = new ApiKey("<API_KEY>"); // However this is
-var client = new ElasticsearchClient("<CLOUD_ID>", apiKey); 
+var client = new ElasticsearchClient("<CLOUD_ID>", apiKey);
 ```

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
-```

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.
+| Frontmatter         | Learn more                  |
+| ------------------- | --------------------------- |
+| `title`             | See [title](./titles.md)    |
+| `navigation_title`  | See [title](./titles.md)    |
+| `applies`           | See [product availability](./applies.md) |

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)

docs/source/syntax/links.md

@@ -2,4 +2,32 @@
 title: Links
 ---
 
-tbd
+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.md)
+```
+
+[Link title](links.md)
+
+```
+[**Hi**, _I'm md_](links.md)
+```
+
+[**Hi**, _I'm md_](links.md)
+
+## 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.md#notes) heading on the [Tables](tables.md) page.
+```