From e407424f99b8fa77c22c006406c8e800d17a79fa Mon Sep 17 00:00:00 2001 From: Jan Calanog Date: Fri, 14 Feb 2025 10:57:32 +0100 Subject: [PATCH 1/3] Add headings --- docs/docset.yml | 3 +- docs/syntax/headings.md | 109 ++++++++++++++++++ src/Elastic.Markdown/Assets/markdown/list.css | 2 +- src/Elastic.Markdown/Assets/markdown/tabs.css | 2 +- .../Assets/markdown/typography.css | 42 ++++++- src/Elastic.Markdown/Assets/toc-nav.ts | 2 +- .../Myst/SectionedHeadingRenderer.cs | 58 ++++++---- .../Slices/Layout/_Breadcrumbs.cshtml | 4 - src/Elastic.Markdown/Slices/_Layout.cshtml | 2 +- 9 files changed, 188 insertions(+), 36 deletions(-) create mode 100644 docs/syntax/headings.md diff --git a/docs/docset.yml b/docs/docset.yml index db544125d..92d8b12a8 100644 --- a/docs/docset.yml +++ b/docs/docset.yml @@ -79,6 +79,7 @@ toc: - folder: syntax children: - file: index.md + - file: headings.md - file: admonitions.md - file: applies.md - file: automated_settings.md @@ -124,4 +125,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..8a0c559c3 --- /dev/null +++ b/docs/syntax/headings.md @@ -0,0 +1,109 @@ +# Headings + +You can have up to 6 levels of headings. But only levels 2 and 3 are displayed in table of contents sidebar. + +## Basics + +::::{tab-set} + +:::{tab-item} Markdown + +```markdown +# Heading 1 +## Heading 2 +### Heading 3 +#### Heading 4 +##### Heading 5 +###### Heading 6 + +``` + +::: + +:::{tab-item} HTML + +```html +
+

+ Heading 1 +

+
+``` + +::: + +:::{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 can also specify a custom anchor link using the following syntax: + +### Default Anchor Link + +::::{tab-set} + +:::{tab-item} Markdown + +```markdown + +## Hello-World + +``` + +::: + +:::{tab-item} Output + +## Hello-World + +::: + +:::: + + +### Custom Anchor Link + +::::{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()