Add headings

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
+              - file: qux.md

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 `<h3>`, 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]
+
+:::
+
+::::

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;

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);
 		}
 

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;
 	}
 }

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);

src/Elastic.Markdown/Myst/SectionedHeadingRenderer.cs

@@ -38,27 +38,43 @@ protected override void Write(HtmlRenderer renderer, HeadingBlock obj)
 
 		var slug = slugTarget.Slugify();
 
-		renderer.Write(@"<section id=""");
-		renderer.Write(slug);
-		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($@"<a class=""headerlink"" href=""#{slug}"" title=""Link to this heading"">¶</a>");
-
-		renderer.Write("</");
-		renderer.Write(headingText);
-		renderer.WriteLine('>');
-
-		renderer.Write("</section>");
-
-		renderer.EnsureLine();
+		if (isRedesign)
+		{
+			renderer.Write(@"<div class=""heading-wrapper"" id=""");
+			renderer.Write(slug);
+			renderer.Write(@""">");
+			renderer.Write('<');
+			renderer.Write(headingText);
+			renderer.WriteAttributes(obj);
+			renderer.Write('>');
+			renderer.Write($"""<a class="headerlink" href="#{slug}">""");
+			renderer.WriteLeafInline(obj);
+			renderer.Write("</a>");
+			renderer.Write("</");
+			renderer.Write(headingText);
+			renderer.WriteLine('>');
+			renderer.Write("</div>");
+			renderer.EnsureLine();
+		}
+		else
+		{
+			renderer.Write(@"<section id=""");
+			renderer.Write(slug);
+			renderer.Write(@""">");
+			renderer.Write('<');
+			renderer.Write(headingText);
+			renderer.WriteAttributes(obj);
+			renderer.Write('>');
+			renderer.WriteLeafInline(obj);
+			// language=html
+			renderer.WriteLine($@"<a class=""headerlink"" href=""#{slug}"" title=""Link to this heading"">¶</a>");
+			renderer.Write("</");
+			renderer.Write(headingText);
+			renderer.WriteLine('>');
+			renderer.Write("</section>");
+			renderer.EnsureLine();
+		}
 	}
 }

src/Elastic.Markdown/Slices/Layout/_Breadcrumbs.cshtml

@@ -18,9 +18,5 @@
 	}
 	<li class="inline text-gray-500 text-sm leading-[1.2em] tracking-[-0.02em]" itemprop="itemListElement" itemscope="" itemtype="https://schema.org/ListItem">
 		<span class="px-1">/</span>
-		<a itemprop="item" href="@Model.CurrentDocument.Url" class="pointer-events-none">
-			<span itemprop="name" class="hover:text-ink">@Model.CurrentDocument.NavigationTitle</span>
-		</a>
-		<meta itemprop="position" content="1">
 	</li>
 </ol>

src/Elastic.Markdown/Slices/_Layout.cshtml

@@ -20,7 +20,7 @@
 			<div class="content-container">
 				@await RenderPartialAsync(_Breadcrumbs.Create(Model))
 			</div>
-			<article class="content-container">
+			<article class="content-container markdown-content">
 				@await RenderBodyAsync()
 			</article>
 			<footer class="content-container mt-20">