diff --git a/docs/docset.yml b/docs/docset.yml index b05780e9d..635e68457 100644 --- a/docs/docset.yml +++ b/docs/docset.yml @@ -26,6 +26,7 @@ external_hosts: - atlassian.net - elastic.dev - visualstudio.com + - wikipedia.org exclude: - '_*.md' subs: @@ -81,6 +82,7 @@ toc: - folder: syntax children: - file: index.md + - file: headings.md - file: admonitions.md - file: applies.md - file: automated_settings.md @@ -126,4 +128,4 @@ toc: - file: bar.md - folder: baz children: - - file: qux.md \ No newline at end of file + - file: qux.md diff --git a/docs/syntax/headings.md b/docs/syntax/headings.md new file mode 100644 index 000000000..bc48f1d31 --- /dev/null +++ b/docs/syntax/headings.md @@ -0,0 +1,100 @@ +# Headings + +You create a heading by adding number signs `#` in front of a word or phrase. The number of number signs you use should correspond to the heading level. For example, to create a heading level three `

`, use three number signs (e.g., `### My Header`). + +## Basics + +::::{tab-set} + +:::{tab-item} Markdown + +```markdown +# Heading 1 +## Heading 2 +### Heading 3 +#### Heading 4 +##### Heading 5 +###### Heading 6 + +``` + +::: + +:::{tab-item} Output + +# Heading 1 + +## Heading 2 + +### Heading 3 + +#### Heading 4 + +##### Heading 5 + +###### Heading 6 + +::: + +:::: + +:::{note} + +- Every page has to start with a level 1 heading. +- You should use only one level 1 heading per page. +- Headings inside directives like tabs or dropdowns causes the table of contents indicator to behave unexpectedly. +- If you are using the same heading text multiple times you should use a custom [anchor link](#anchor-links) to avoid conflicts. + +::: + +## Anchor Links + +By default, the anchor links are generated based on the heading text. +You will get a hyphened, lowercase, alphanumeric version of any string you please, with any [diacritics](https://en.wikipedia.org/wiki/Diacritic) removed, whitespace and dashes collapsed, and whitespace trimmed. + +### Default Anchor Links + +::::{tab-set} + +:::{tab-item} Markdown + +```markdown + +#### Hello-World + +``` + +::: + +:::{tab-item} Output + +#### Hello-World + +::: + +:::: + + +### Custom Anchor Links + +You can also specify a custom anchor link using the following syntax. + +::::{tab-set} + +:::{tab-item} Markdown + +```markdown + +#### Heading [#custom-anchor] + +``` + +::: + +:::{tab-item} Output + +#### Heading [#custom-anchor] + +::: + +:::: diff --git a/src/Elastic.Markdown/Assets/markdown/list.css b/src/Elastic.Markdown/Assets/markdown/list.css index 1d9e79e0e..e993a59df 100644 --- a/src/Elastic.Markdown/Assets/markdown/list.css +++ b/src/Elastic.Markdown/Assets/markdown/list.css @@ -1,4 +1,4 @@ -#elastic-docs-v3 { +.markdown-content { ol,ul { font-family: "Inter", sans-serif; @apply text-base text-body mb-6; diff --git a/src/Elastic.Markdown/Assets/markdown/tabs.css b/src/Elastic.Markdown/Assets/markdown/tabs.css index 9457fa676..b35c71c93 100644 --- a/src/Elastic.Markdown/Assets/markdown/tabs.css +++ b/src/Elastic.Markdown/Assets/markdown/tabs.css @@ -15,7 +15,7 @@ } .tabs-content { - @apply w-full order-99 border-t-1 border-gray-300 pl-6 pt-4 z-0 hidden; + @apply w-full order-99 border-t-1 border-gray-300 px-6 pt-4 z-0 hidden; transform: translateY(-1px); } diff --git a/src/Elastic.Markdown/Assets/markdown/typography.css b/src/Elastic.Markdown/Assets/markdown/typography.css index 920a5fe55..806fc68d4 100644 --- a/src/Elastic.Markdown/Assets/markdown/typography.css +++ b/src/Elastic.Markdown/Assets/markdown/typography.css @@ -1,26 +1,56 @@ -#elastic-docs-v3 { +.markdown-content { + + font-size: 16px; h1 { font-family: "Mier B", "Inter", sans-serif; - @apply text-4xl text-black mb-6 mt-4; + @apply text-5xl text-black mb-6 mt-5; line-height: 1.2em; letter-spacing: -0.04em; } h2 { font-family: "Mier B", "Inter", sans-serif; - @apply text-2xl text-black mb-6 mt-4; + @apply text-4xl text-black mb-6 mt-8; line-height: 1.2em; - letter-spacing: -0.02em; + letter-spacing: -0.04em; } h3 { font-family: "Mier B", "Inter", sans-serif; - @apply text-xl text-black font-bold mb-6 mt-4; + @apply text-2xl text-black mb-6 mt-6; + line-height: 1.2em; + letter-spacing: -0.02em; + } + + h4 { + font-family: "Mier B", "Inter", sans-serif; + @apply text-base text-black font-bold mb-5 mt-5; + line-height: 1.2em; + letter-spacing: -0.02em; + } + + h5 { + font-family: "Mier B", "Inter", sans-serif; + @apply text-sm text-black font-bold mb-4 mt-5; + line-height: 1.2em; + letter-spacing: -0.02em; + } + + h6 { + font-family: "Mier B", "Inter", sans-serif; + @apply text-xs text-black font-bold mb-3 mt-3; line-height: 1.2em; letter-spacing: -0.02em; } + h1, h2, h3, h4, h5, h6 { + a { + font-family: "Mier B", "Inter", sans-serif; + @apply text-black hover:text-black no-underline; + } + } + p { font-family: "Inter", sans-serif; @apply text-base text-ink text-body mb-6; @@ -30,6 +60,6 @@ a { font-family: "Inter", sans-serif; - @apply text-blue-elastic underline hover:text-blue-800; + @apply text-blue-elastic hover:text-blue-800 underline; } } diff --git a/src/Elastic.Markdown/Assets/toc-nav.ts b/src/Elastic.Markdown/Assets/toc-nav.ts index 21d1ad5cc..20b55fa09 100644 --- a/src/Elastic.Markdown/Assets/toc-nav.ts +++ b/src/Elastic.Markdown/Assets/toc-nav.ts @@ -32,7 +32,7 @@ function findCurrentTocLinks(elements: TocElements): HTMLAnchorElement[] { } currentTop = rect.top; const foundLink = elements.tocLinks.find(link => - link.getAttribute('href') === `#${heading.closest('section')?.id}` + link.getAttribute('href') === `#${heading.closest('.heading-wrapper')?.id}` ); if (foundLink) { currentTocLinks.push(foundLink); diff --git a/src/Elastic.Markdown/Myst/SectionedHeadingRenderer.cs b/src/Elastic.Markdown/Myst/SectionedHeadingRenderer.cs index cd1c4a8fa..831f93f52 100644 --- a/src/Elastic.Markdown/Myst/SectionedHeadingRenderer.cs +++ b/src/Elastic.Markdown/Myst/SectionedHeadingRenderer.cs @@ -38,27 +38,43 @@ protected override void Write(HtmlRenderer renderer, HeadingBlock obj) var slug = slugTarget.Slugify(); - renderer.Write(@"
"); + var isRedesign = Environment.GetEnvironmentVariable("REDESIGN") == "true"; - renderer.Write('<'); - renderer.Write(headingText); - renderer.WriteAttributes(obj); - renderer.Write('>'); - - renderer.WriteLeafInline(obj); - - - // language=html - renderer.WriteLine($@""); - - renderer.Write("'); - - renderer.Write("
"); - - renderer.EnsureLine(); + if (isRedesign) + { + renderer.Write(@"
"); + renderer.Write('<'); + renderer.Write(headingText); + renderer.WriteAttributes(obj); + renderer.Write('>'); + renderer.Write($""""""); + renderer.WriteLeafInline(obj); + renderer.Write(""); + renderer.Write("'); + renderer.Write("
"); + renderer.EnsureLine(); + } + else + { + renderer.Write(@"
"); + renderer.Write('<'); + renderer.Write(headingText); + renderer.WriteAttributes(obj); + renderer.Write('>'); + renderer.WriteLeafInline(obj); + // language=html + renderer.WriteLine($@""); + renderer.Write("'); + renderer.Write("
"); + renderer.EnsureLine(); + } } } diff --git a/src/Elastic.Markdown/Slices/Layout/_Breadcrumbs.cshtml b/src/Elastic.Markdown/Slices/Layout/_Breadcrumbs.cshtml index 790c0baca..768fb0852 100644 --- a/src/Elastic.Markdown/Slices/Layout/_Breadcrumbs.cshtml +++ b/src/Elastic.Markdown/Slices/Layout/_Breadcrumbs.cshtml @@ -18,9 +18,5 @@ }
  • / - - @Model.CurrentDocument.NavigationTitle - -
    • diff --git a/src/Elastic.Markdown/Slices/_Layout.cshtml b/src/Elastic.Markdown/Slices/_Layout.cshtml index 2ca9c50d8..4bbd5b078 100644 --- a/src/Elastic.Markdown/Slices/_Layout.cshtml +++ b/src/Elastic.Markdown/Slices/_Layout.cshtml @@ -20,7 +20,7 @@
    @await RenderPartialAsync(_Breadcrumbs.Create(Model))
    -
    +
    @await RenderBodyAsync()