Remove 'title' frontmatter and improve title handling logic

Mpdreamz · Mpdreamz · commit d66c141e09e2 · 2025-01-14T19:29:34.000+01:00
Replaced the 'title' frontmatter across documentation with level 1 headings, ensuring compliance with new markdown conventions. Updated the rendering logic in the codebase to emit warnings for deprecated titles and fallback to file names if no headings are found. These changes simplify title management and enhance markdown compatibility.
diff --git a/docs/source/configure/content-set/attributes.md b/docs/source/configure/content-set/attributes.md
@@ -1,5 +1,3 @@
----
-title: Attributes
----
+# Attributes
 
 tbd
diff --git a/docs/source/configure/content-set/file-structure.md b/docs/source/configure/content-set/file-structure.md
@@ -1,5 +1,3 @@
----
-title: File structure
----
+# File structure
 
 tbd
diff --git a/docs/source/configure/content-set/index.md b/docs/source/configure/content-set/index.md
@@ -1,8 +1,9 @@
 ---
-title: Content set configuration
 navigation_title: Content set
 ---
 
+# Content set configuration
+
 Now we'll zoom into the AsciiDoc book level, and explore the V3 equivalent: content sets. At the book level, the system consists of:
 
 | System property | Asciidoc | V3 |
diff --git a/docs/source/configure/content-set/navigation.md b/docs/source/configure/content-set/navigation.md
@@ -1,5 +1,3 @@
----
-title: Navigation
----
+# Navigation
 
 tbd
diff --git a/docs/source/configure/index.md b/docs/source/configure/index.md
@@ -1,8 +1,9 @@
 ---
-title: Configure Elastic Docs
 navigation_title: Configuration reference
 ---
 
+# Configure Elastic Docs
+
 * [Page configuration](./page.md)
 * [Content-set configuration](./content-set/index.md)
 * [Site configuration](./site/index.md)
diff --git a/docs/source/configure/page.md b/docs/source/configure/page.md
@@ -1,8 +1,9 @@
 ---
-title: Page configuration
 navigation_title: Page
 ---
 
+# Page configuration
+
 tbd
 
 go into frontmatter here?
diff --git a/docs/source/configure/site/content.md b/docs/source/configure/site/content.md
@@ -1,6 +1,4 @@
----
-title: Content config
----
+# Content config
 
 In both the AsciiDoctor- and V3-based system, there is site-wide configuration where you list all content sources, where to find those sources, and in what order they should be added to the site.
 
diff --git a/docs/source/configure/site/index.md b/docs/source/configure/site/index.md
@@ -1,8 +1,9 @@
 ---
-title: Site configuration
 navigation_title: Site
 ---
 
+# Site configuration
+
 Start by understanding how the new V3 system works at the site level compared to how our custom AsciiDoctor system works. The system consists of:
 
 
diff --git a/docs/source/configure/site/landing-page.md b/docs/source/configure/site/landing-page.md
@@ -1,5 +1,3 @@
----
-title: Landing page
----
+# Landing page
 
 tbd
diff --git a/docs/source/configure/site/redirects.md b/docs/source/configure/site/redirects.md
@@ -1,6 +1,4 @@
----
-title: Redirects
----
+# Redirects
 
 ## From an elastic.co/guide page
 
diff --git a/docs/source/configure/site/shared-attributes.md b/docs/source/configure/site/shared-attributes.md
@@ -1,6 +1,4 @@
----
-title: Shared attributes
----
+# Shared attributes
 
 To promote consistency across documentation, AsciiDoc uses shared attributes for common terms, URLs, and versions.
 
diff --git a/docs/source/contribute/index.md b/docs/source/contribute/index.md
@@ -1,8 +1,9 @@
 ---
-title: Elastic Docs contribution guide
 navigation_title: Contribute
 ---
 
+# Elastic Docs contribution guide
+
 Welcome, **contributor**!
 
 Whether you're a technical writer or you've only edited Elastic docs once or twice, you're a valued contributor. Every word matters!
diff --git a/docs/source/contribute/locally.md b/docs/source/contribute/locally.md
@@ -1,6 +1,4 @@
----
-title: Contribute locally
----
+# Contribute locally
 
 Follow these steps to contribute to Elastic docs.
 * [Step 1: Install `docs-builder`](#step-one)
diff --git a/docs/source/contribute/on-the-web.md b/docs/source/contribute/on-the-web.md
@@ -1,6 +1,4 @@
----
-title: Contribute on the web
----
+# Contribute on the web
 
 :::{warning}
 This feature is not supported yet. See [#171](https://github.com/elastic/docs-builder/issues/171) for more information.
diff --git a/docs/source/development/index.md b/docs/source/development/index.md
@@ -1,6 +1,7 @@
 ---
-title: Development Guide
 navigation_title: Development
 ---
 
+# Development Guide
+
 TODO write development documentation here
diff --git a/docs/source/development/link-validation.md b/docs/source/development/link-validation.md
@@ -1,6 +1,4 @@
----
-title: Link validation
----
+# Link validation
 
 * See the [RFC](https://docs.google.com/document/d/1fZNeJCVLKu19s4WIKkkqrHyE9YlWQHNed94Y_V7ofRI/edit?tab=t.0#heading=h.z8tixe192fr4).
 * Infrastructure lives in [docs-infra](https://github.com/elastic/docs-infra).
diff --git a/docs/source/index.md b/docs/source/index.md
@@ -1,6 +1,4 @@
----
-title: Welcome to Elastic Docs v3
----
+# Welcome to Elastic Docs v3
 
 Elastic Docs V3 is our next-generation documentation platform designed to improve the experience of learning, using, and contributing to Elastic products. Built on a foundation of modern authoring tools and scalable infrastructure, V3 offers faster builds, streamlined versioning, and enhanced navigation to guide users through Elastic’s complex ecosystem.
 
diff --git a/docs/source/migration/engineering.md b/docs/source/migration/engineering.md
@@ -1,6 +1,4 @@
----
-title: Reference docs guidelines
----
+# Reference docs guidelines
 
 ## Engineering ownership of reference documentation
 
diff --git a/docs/source/migration/freeze/gh-action.md b/docs/source/migration/freeze/gh-action.md
@@ -1,6 +1,4 @@
----
-title: GH Action
----
+# GH Action
 
 ## Overview
 This GitHub Action enforces documentation freezes by adding comments to pull requests that modify `.asciidoc` files. It complements the use of `CODEOWNERS` to ensure changes during a freeze period are reviewed and approved by the `@docs-freeze-team`.
diff --git a/docs/source/migration/freeze/index.md b/docs/source/migration/freeze/index.md
@@ -1,6 +1,4 @@
----
-title: Documentation Freeze
----
+# Documentation Freeze
 
 During the documentation freeze, the Docs team will focus almost entirely on migration tasks to ensure all content is successfully migrated and will handle only emergency documentation requests and release-related activities. When the migration is complete, writers will address documentation requests needed during the documentation freeze, ensuring that updates align with the new information architecture and format.
 
diff --git a/docs/source/migration/guide/file-structure.md b/docs/source/migration/guide/file-structure.md
@@ -1,6 +1,4 @@
----
-title: File structure
----
+# File structure
 
 In both the AsciiDoc- and V3-based systems, file structure is largely independent from the resulting site navigation.
 
diff --git a/docs/source/migration/guide/index.md b/docs/source/migration/guide/index.md
@@ -1,6 +1,4 @@
----
-title: Migration Guide
----
+# Migration Guide
 
 How to migrate content from Asciidoc to V3.
 
diff --git a/docs/source/migration/guide/mapping.md b/docs/source/migration/guide/mapping.md
@@ -1,8 +1,9 @@
 ---
-title: Book to content set mapping
 navigation_title: What books are migrating
 ---
 
+# Book to content set mapping
+
 What full books are staying in Asciidoc? What books are migrating `main`/`master`? See the table below.
 
 | Title                                                                                                    | Current Version | Sources                                                                                                                                                                                                                                                                                              | Migrate to       |
diff --git a/docs/source/migration/ia.md b/docs/source/migration/ia.md
@@ -1,8 +1,9 @@
 ---
-title: Improved information architecture
 navigation_title: New IA
 ---
 
+# Improved information architecture
+
 The improved information architecture fundamentally transforms how we organize and present Elastic Docs. By addressing longstanding challenges—such as fragmented content across many books and duplicated information—this new structure introduces a cohesive framework that emphasizes clarity, usability, and alignment with user goals. These updates are designed to create a seamless experience for both readers and contributors, fostering greater understanding of our products and their benefits.
 
 The new IA design does the following:
diff --git a/docs/source/migration/index.md b/docs/source/migration/index.md
@@ -1,8 +1,9 @@
 ---
-title: "Migration to docs-builder"
 navigation_title: Migration
 ---
 
+# "Migration to docs-builder"
+
 We are ready to migrate our documentation to our new build system, [elastic/docs-builder](https://github.com/elastic/docs-builder)!
 
 :::{important}
diff --git a/docs/source/migration/syntax.md b/docs/source/migration/syntax.md
@@ -1,8 +1,9 @@
 ---
-title: New syntax
 navigation_title: New syntax
 ---
 
+# New syntax
+
 With the migration to Elastic Docs v3, the primary format for all Elastic Docs is transitioning from AsciiDoc to Markdown. Why Markdown? Markdown is already an industry standard across the industry, and 90% of Elastic developers are comfortable working with Markdown syntax [[source](https://docs.google.com/presentation/d/1morhFX4tyVB0A2f1_fnySzeJvPYf0kXGjVVYU_lVRys/edit#slide=id.g13b75c8f1f3_0_463)].
 
 See our [syntax guide](../syntax/index.md) to learn more about the flavor of Markdown that we support.
diff --git a/docs/source/migration/versioning.md b/docs/source/migration/versioning.md
@@ -1,6 +1,4 @@
----
-title: Consolidated versioning
----
+# Consolidated versioning
 
 As part of the new information architecture, pages with varying versioning schemes are now interwoven, creating the opportunity and necessity to rethink the scope and versioning of each page. The previous approach of creating entirely separate docs sets for every minor version resulted in fragmentation and unnecessary duplication. Consolidating versioning resolves these issues while maintaining clarity and usability.
 
diff --git a/docs/source/syntax/admonitions.md b/docs/source/syntax/admonitions.md
@@ -1,6 +1,4 @@
----
-title: Admonitions
----
+# 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.
 
diff --git a/docs/source/syntax/applies.md b/docs/source/syntax/applies.md
@@ -1,5 +1,4 @@
 ---
-title: Product Availability
 applies:
   stack: ga 8.1
   serverless: tech-preview
@@ -8,6 +7,8 @@ applies:
   ece: unavailable
 ---
 
+# Product Availability
+
 
 Using yaml frontmatter pages can explicitly indicate to each deployment targets availability and lifecycle status
 
diff --git a/docs/source/syntax/automated_settings.md b/docs/source/syntax/automated_settings.md
@@ -1,6 +1,4 @@
----
-title: Automated settings reference
----
+# Automated settings reference
 
 Elastic Docs V3 supports the ability to build a markdown settings reference from a YAML source file.
 
diff --git a/docs/source/syntax/code.md b/docs/source/syntax/code.md
@@ -1,6 +1,4 @@
----
-title: Code blocks
----
+# Code blocks
 
 Code blocks can be used to display multiple lines of code. They preserve formatting and provide syntax highlighting when possible.
 
diff --git a/docs/source/syntax/conditionals.md b/docs/source/syntax/conditionals.md
@@ -1,6 +1,4 @@
----
-title: Conditionals
----
+# Conditionals
 
 ```{warning}
 This feature is not currently supported in Elastic Docs V3.
diff --git a/docs/source/syntax/dropdowns.md b/docs/source/syntax/dropdowns.md
@@ -1,6 +1,4 @@
----
-title: Dropdowns
----
+# Dropdowns
 
 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.
 
diff --git a/docs/source/syntax/example_blocks.md b/docs/source/syntax/example_blocks.md
@@ -1,6 +1,4 @@
----
-title: Example blocks
----
+# Example blocks
 
 ```{warning}
 This feature is not currently supported in Elastic Docs V3.
diff --git a/docs/source/syntax/file_inclusion.md b/docs/source/syntax/file_inclusion.md
@@ -1,7 +1,4 @@
----
-title: File inclusion
-test: hi
----
+# File inclusion
 
 File inclusion is useful for
 - including entire pages in a content set (usually done in the `docset.yml` file)
diff --git a/docs/source/syntax/frontmatter.md b/docs/source/syntax/frontmatter.md
@@ -1,8 +1,6 @@
----
-title: Frontmatter
----
+# Frontmatter
 
-Each MD file referenced in the TOC requires frontmatter. Frontmatter is YAML-formatted metadata about a page, at the beginning of each file.
+Each MD file referenced in the TOC may optionally define a frontmatter. Frontmatter is YAML-formatted metadata about a page, at the beginning of each file.
 
 Supported frontmatter includes:
 
diff --git a/docs/source/syntax/images.md b/docs/source/syntax/images.md
@@ -1,6 +1,4 @@
----
-title: Images
----
+# Images
 
 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
diff --git a/docs/source/syntax/index.md b/docs/source/syntax/index.md
@@ -1,6 +1,4 @@
----
-title: Syntax guide
----
+# Syntax guide
 
 Elastic docs V3 supports markdown and various directives that add additional functionality to markdown.
 
diff --git a/docs/source/syntax/links.md b/docs/source/syntax/links.md
@@ -1,6 +1,4 @@
----
-title: Links
----
+# Links
 
 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.
 
diff --git a/docs/source/syntax/passthrough.md b/docs/source/syntax/passthrough.md
@@ -1,6 +1,4 @@
----
-title: Passthrough blocks
----
+# Passthrough blocks
 
 ```{warning}
 This feature is not currently supported in Elastic Docs V3.
diff --git a/docs/source/syntax/sidebars.md b/docs/source/syntax/sidebars.md
@@ -1,6 +1,4 @@
----
-title: Sidebars
----
+# Sidebars
 
 ```{warning}
 This feature is not currently supported in Elastic Docs V3.
diff --git a/docs/source/syntax/substitutions.md b/docs/source/syntax/substitutions.md
@@ -1,11 +1,12 @@
 ---
-title: Substitutions
 sub:
   frontmatter_key: "Front Matter Value"
   a-key-with-dashes: "A key with dashes"
   version: 7.17.0
 ---
 
+# Substitutions
+
 Substitutions can be defined in two places:
 
 1. In the `frontmatter` YAML within a file.
diff --git a/docs/source/syntax/sundries.md b/docs/source/syntax/sundries.md
@@ -1,6 +1,4 @@
----
-title: Sundries
----
+# Sundries
 
 ## Inline text formatting
 
diff --git a/docs/source/syntax/tables.md b/docs/source/syntax/tables.md
@@ -1,6 +1,4 @@
----
-title: Tables
----
+# Tables
 
 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:
 
diff --git a/docs/source/syntax/tabs.md b/docs/source/syntax/tabs.md
diff --git a/docs/source/syntax/tagged_regions.md b/docs/source/syntax/tagged_regions.md
diff --git a/docs/source/syntax/titles.md b/docs/source/syntax/titles.md
diff --git a/docs/source/testing/cross-links.md b/docs/source/testing/cross-links.md
diff --git a/docs/source/testing/index.md b/docs/source/testing/index.md
diff --git a/docs/source/testing/nested/index.md b/docs/source/testing/nested/index.md
diff --git a/docs/source/testing/req.md b/docs/source/testing/req.md
diff --git a/src/Elastic.Markdown/IO/MarkdownFile.cs b/src/Elastic.Markdown/IO/MarkdownFile.cs
diff --git a/src/Elastic.Markdown/Myst/ParserContext.cs b/src/Elastic.Markdown/Myst/ParserContext.cs
diff --git a/src/docs-generator/Cli/Commands.cs b/src/docs-generator/Cli/Commands.cs
diff --git a/tests/Elastic.Markdown.Tests/Directives/AppliesBlockTests.cs b/tests/Elastic.Markdown.Tests/Directives/AppliesBlockTests.cs
diff --git a/tests/Elastic.Markdown.Tests/Directives/DirectiveBaseTests.cs b/tests/Elastic.Markdown.Tests/Directives/DirectiveBaseTests.cs
diff --git a/tests/Elastic.Markdown.Tests/FileInclusion/IncludeTests.cs b/tests/Elastic.Markdown.Tests/FileInclusion/IncludeTests.cs
diff --git a/tests/Elastic.Markdown.Tests/FrontMatter/ProductConstraintTests.cs b/tests/Elastic.Markdown.Tests/FrontMatter/ProductConstraintTests.cs
diff --git a/tests/Elastic.Markdown.Tests/FrontMatter/YamlFrontMatterTests.cs b/tests/Elastic.Markdown.Tests/FrontMatter/YamlFrontMatterTests.cs
diff --git a/tests/Elastic.Markdown.Tests/Inline/AnchorLinkTests.cs b/tests/Elastic.Markdown.Tests/Inline/AnchorLinkTests.cs
diff --git a/tests/Elastic.Markdown.Tests/Inline/CommentTest.cs b/tests/Elastic.Markdown.Tests/Inline/CommentTest.cs
diff --git a/tests/Elastic.Markdown.Tests/Inline/DirectiveBlockLinkTests.cs b/tests/Elastic.Markdown.Tests/Inline/DirectiveBlockLinkTests.cs
diff --git a/tests/Elastic.Markdown.Tests/Inline/InlineLinkTests.cs b/tests/Elastic.Markdown.Tests/Inline/InlineLinkTests.cs
diff --git a/tests/Elastic.Markdown.Tests/Inline/InlneBaseTests.cs b/tests/Elastic.Markdown.Tests/Inline/InlneBaseTests.cs
diff --git a/tests/Elastic.Markdown.Tests/Inline/SubstitutionTest.cs b/tests/Elastic.Markdown.Tests/Inline/SubstitutionTest.cs
