various docs / syntax guide updates

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

@@ -73,6 +73,10 @@ This is an important notice.
 
 ## Collapsible admonitions
 
+```{tip}
+Also see [dropdowns](./dropdowns.md).
+```
+
 Use `:open: <bool>` to make an admonition collapsible.
 
 ```markdown

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,34 @@
 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.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.

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          |
+% ``` -->
+%
+% <!-- ## `{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!
+% ```