diff --git a/README.md b/README.md index b22e5842..990b1ddb 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ -# docs-builder. +# docs-builder. -You've reached the home of the latest incarnation of the documentation tooling. +You've reached the home of the latest incarnation of the documentation tooling. This repository is host to: @@ -48,7 +48,7 @@ docker run -v "./.git:/app/.git" -v "./docs:/app/docs" -v "./.artifacts:/app/.ar This ensures `.git`/`docs` and `.artifacts` (the default output directory) are mounted. -The tool will default to incremental compilation. +The tool will default to incremental compilation. Only the changed files on subsequent runs will be compiled unless you pass `--force` to force a new compilation. @@ -66,7 +66,7 @@ docker run -v "./.git:/app/.git" -v "./docs:/app/docs" -v "./.artifacts:/app/.ar -p 8080:8080 ghcr.io/elastic/docs-builder:edge serve ``` -Each page is compiled on demand as you browse http://localhost:8080 and is never cached so changes to files and +Each page is compiled on demand as you browse http://localhost:8080 and is never cached so changes to files and navigation will always be reflected upon refresh. Note the docker image is `linux-x86` and will be somewhat slower to invoke on OSX due to virtualization. @@ -74,7 +74,7 @@ Note the docker image is `linux-x86` and will be somewhat slower to invoke on OS ## Github Action -The `docs-builder` tool is available as github action. +The `docs-builder` tool is available as github action. Since it runs from a precompiled distroless image `~25mb` it's able to execute snappy. (no need to wait for building the tool itself) @@ -93,8 +93,8 @@ jobs: ### GitHub Pages -To setup the tool to publish to GitHub pages use the following configuration. -**NOTE**: In the near feature we'll make this a dedicated single step Github ction +To setup the tool to publish to GitHub pages use the following configuration. +**NOTE**: In the near feature we'll make this a dedicated single step Github ction ```yaml steps: @@ -112,10 +112,10 @@ steps: uses: actions/upload-pages-artifact@v3.0.1 with: path: .artifacts/docs/html - + - name: Deploy artifact id: deployment - uses: actions/deploy-pages@v4.0.5 + uses: actions/deploy-pages@v4.0.5 ``` Note `prefix:` is required to inject the appropiate `--path-prefix` argument to `docs-builder` @@ -135,7 +135,7 @@ If you have dotnet 8 installed you can use its CLI to publish a self-contained ` binary. (On my M2 Pro mac the binary is currently 13mb) ```bash -$ dotnet publish "src/docs-builder/docs-builder.csproj" -c Release -o .artifacts/publish \ +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 ``` @@ -147,5 +147,5 @@ The resulting binary `./.artifacts/publish/docs-builder` will run on machines wi To test performance it's best to build the binary and run outside of docker: -For refence here's the `markitpy-doc` docset (50k markdown files) currently takes `14s` vs `several minutes` compared to +For refence here's the `markitpy-doc` docset (50k markdown files) currently takes `14s` vs `several minutes` compared to existing surveyed tools diff --git a/docs/source/syntax/admonitions.md b/docs/source/syntax/admonitions.md index ba584d23..f8550b50 100644 --- a/docs/source/syntax/admonitions.md +++ b/docs/source/syntax/admonitions.md @@ -4,10 +4,6 @@ title: Admonitions Admonitions allow you to highlight important information with varying levels of priority. In software documentation, these blocks are used to emphasize risks, provide helpful advice, or share relevant but non-critical details. -```{attention} -Asciidoc and V3 currently support different admonition types. See [#106](https://github.com/elastic/docs-builder/issues/106) for details. -``` - ## Basic admonitions Admonitions can span multiple lines and support inline formatting. @@ -19,9 +15,9 @@ Admonitions can span multiple lines and support inline formatting. ### Available admonition types - `note` -- `caution` +- `warning` - `tip` -- `attention` +- `important` ### Syntax @@ -40,18 +36,18 @@ It can span multiple lines and supports inline formatting. This is a note. ::: -**Caution** +**Warning** You could permanently lose data or leak sensitive information. ```markdown -:::{caution} -This is a caution. +:::{warning} +This is a warning. ::: ``` -```{caution} -This is a caution. +```{warning} +This is a warning. ``` **Tip** @@ -68,21 +64,20 @@ This is a tip. This is a tip. ``` -**Attention** +**Important** Ignoring this information could impact performance or the stability of your system. ```markdown -:::{attention} -This is an attention. +:::{important} +This is an important notice. ::: ``` -```{attention} -This is an attention. +```{important} +This is an important notice. ``` - ```` ````{tab-item} Asciidoc Syntax diff --git a/docs/source/syntax/conditionals.md b/docs/source/syntax/conditionals.md index f62dfc57..1c3d1af4 100644 --- a/docs/source/syntax/conditionals.md +++ b/docs/source/syntax/conditionals.md @@ -2,6 +2,6 @@ title: Conditionals --- -```{caution} +```{warning} This feature is not currently supported in Elastic Docs V3. ``` \ No newline at end of file diff --git a/docs/source/syntax/example_blocks.md b/docs/source/syntax/example_blocks.md index 92896cbf..31777828 100644 --- a/docs/source/syntax/example_blocks.md +++ b/docs/source/syntax/example_blocks.md @@ -2,6 +2,6 @@ title: Example blocks --- -```{caution} +```{warning} This feature is not currently supported in Elastic Docs V3. ``` \ No newline at end of file diff --git a/docs/source/syntax/images.md b/docs/source/syntax/images.md index 02a6f976..b6f20b0b 100644 --- a/docs/source/syntax/images.md +++ b/docs/source/syntax/images.md @@ -8,7 +8,7 @@ Images can be referenced from the top-level `_static` dir or a local image dir. ## Screenshots -```{caution} +```{warning} This feature is not currently supported in Elastic Docs V3. ``` diff --git a/docs/source/syntax/passthrough.md b/docs/source/syntax/passthrough.md index d9525ddc..61b64518 100644 --- a/docs/source/syntax/passthrough.md +++ b/docs/source/syntax/passthrough.md @@ -2,6 +2,6 @@ title: Passthrough blocks --- -```{caution} +```{warning} This feature is not currently supported in Elastic Docs V3. ``` \ No newline at end of file diff --git a/docs/source/syntax/sidebars.md b/docs/source/syntax/sidebars.md index 0ec2b60b..5d141033 100644 --- a/docs/source/syntax/sidebars.md +++ b/docs/source/syntax/sidebars.md @@ -2,6 +2,6 @@ title: Sidebars --- -```{caution} +```{warning} This feature is not currently supported in Elastic Docs V3. ``` \ No newline at end of file diff --git a/docs/source/syntax/tagged_regions.md b/docs/source/syntax/tagged_regions.md index 69a1d5b7..04325eed 100644 --- a/docs/source/syntax/tagged_regions.md +++ b/docs/source/syntax/tagged_regions.md @@ -2,6 +2,6 @@ title: Tagged regions --- -```{caution} +```{warning} This feature is not currently supported in Elastic Docs V3. See [File inclusion](./file_inclusion.md) for an alternative. ``` diff --git a/src/Elastic.Markdown/Myst/Directives/DirectiveBlockParser.cs b/src/Elastic.Markdown/Myst/Directives/DirectiveBlockParser.cs index e28a6f1f..4b5a2727 100644 --- a/src/Elastic.Markdown/Myst/Directives/DirectiveBlockParser.cs +++ b/src/Elastic.Markdown/Myst/Directives/DirectiveBlockParser.cs @@ -30,7 +30,7 @@ public DirectiveBlockParser() private Dictionary _admonitionData = new(); - private readonly string[] _admonitions = [ "attention", "caution", "note", "tip" ]; + private readonly string[] _admonitions = [ "important", "warning", "note", "tip" ]; private readonly string[] _versionBlocks = [ "versionadded", "versionchanged", "versionremoved", "deprecated" ]; @@ -56,12 +56,12 @@ public DirectiveBlockParser() { "margin", 4 }, { "sidebar", 4 }, { "code-cell", 8 }, - { "admonition", 3 }, + { "attention", 3 }, + { "caution", 3 }, { "danger", 3 }, { "error", 3 }, { "hint", 3 }, - { "important", 3 }, { "seealso", 3 } }.ToFrozenDictionary(); diff --git a/tests/Elastic.Markdown.Tests/Directives/AdmonitionTests.cs b/tests/Elastic.Markdown.Tests/Directives/AdmonitionTests.cs index baed992a..d328b67e 100644 --- a/tests/Elastic.Markdown.Tests/Directives/AdmonitionTests.cs +++ b/tests/Elastic.Markdown.Tests/Directives/AdmonitionTests.cs @@ -23,10 +23,10 @@ A regular paragraph. public void SetsCorrectAdmonitionType() => Block!.Admonition.Should().Be(directive); } -public class CautionTests(ITestOutputHelper output) : AdmonitionTests(output, "caution") +public class WarningTests(ITestOutputHelper output) : AdmonitionTests(output, "warning") { [Fact] - public void SetsTitle() => Block!.Title.Should().Be("Caution"); + public void SetsTitle() => Block!.Title.Should().Be("Warning"); } public class NoteTests(ITestOutputHelper output) : AdmonitionTests(output, "note") @@ -41,10 +41,10 @@ public class TipTests(ITestOutputHelper output) : AdmonitionTests(output, "tip") public void SetsTitle() => Block!.Title.Should().Be("Tip"); } -public class AttentionTests(ITestOutputHelper output) : AdmonitionTests(output, "attention") +public class ImportantTests(ITestOutputHelper output) : AdmonitionTests(output, "important") { - [Fact] - public void SetsTitle() => Block!.Title.Should().Be("Attention"); + [Fact] + public void SetsTitle() => Block!.Title.Should().Be("Important"); } public class NoteTitleTests(ITestOutputHelper output) : DirectiveTest(output, @@ -82,4 +82,3 @@ A regular paragraph. [Fact] public void SetsDropdownOpen() => Block!.DropdownOpen.Should().BeTrue(); } - diff --git a/tests/Elastic.Markdown.Tests/Directives/AdmonitionUnsupportedTests.cs b/tests/Elastic.Markdown.Tests/Directives/AdmonitionUnsupportedTests.cs index 80223d39..ab5e2af1 100644 --- a/tests/Elastic.Markdown.Tests/Directives/AdmonitionUnsupportedTests.cs +++ b/tests/Elastic.Markdown.Tests/Directives/AdmonitionUnsupportedTests.cs @@ -29,7 +29,8 @@ A regular paragraph. public class DangerTests(ITestOutputHelper output) : AdmonitionUnsupportedTests(output, "danger"); public class ErrorTests(ITestOutputHelper output) : AdmonitionUnsupportedTests(output, "error"); public class HintTests(ITestOutputHelper output) : AdmonitionUnsupportedTests(output, "hint"); -public class ImportantTests(ITestOutputHelper output) : AdmonitionUnsupportedTests(output, "important"); +public class AttentionTests(ITestOutputHelper output) : AdmonitionUnsupportedTests(output, "attention"); +public class CautionTests(ITestOutputHelper output) : AdmonitionUnsupportedTests(output, "caution"); public class SeeAlsoTests(ITestOutputHelper output) : AdmonitionUnsupportedTests(output, "seealso"); public class AdmonitionTitleTests(ITestOutputHelper output) : AdmonitionUnsupportedTests(output, "admonition"); // ReSharper restore UnusedType.Global diff --git a/tests/Elastic.Markdown.Tests/Inline/DirectiveBlockLinkTests.cs b/tests/Elastic.Markdown.Tests/Inline/DirectiveBlockLinkTests.cs index 777bfde0..91be9bef 100644 --- a/tests/Elastic.Markdown.Tests/Inline/DirectiveBlockLinkTests.cs +++ b/tests/Elastic.Markdown.Tests/Inline/DirectiveBlockLinkTests.cs @@ -13,9 +13,9 @@ namespace Elastic.Markdown.Tests.Inline; public abstract class DirectiveBlockLinkTests(ITestOutputHelper output, [LanguageInjection("markdown")] string content) : InlineTest(output, $$""" -```{caution} +```{warning} :name: caution_ref -This is a 'caution' admonition +This is a 'warning' admonition ``` {{content}} @@ -31,9 +31,9 @@ protected override void AddToFileSystem(MockFileSystem fileSystem) title: Special Requirements --- -```{attention} +```{important} :name: hint_ref -This is a 'caution' admonition +This is a 'important' admonition ``` """; fileSystem.AddFile(@"docs/source/testing/req.md", inclusion);