diff --git a/MarkdownGuide.md b/MarkdownGuide.md index 5bb8710c111..15619dd9692 100644 --- a/MarkdownGuide.md +++ b/MarkdownGuide.md @@ -4,6 +4,10 @@ This guide covers Markdown-specific syntax and formatting conventions used in Co ## Table of Contents +- [Site structure](#site-structure) + - [Docs repository](#docs-repository) + - [Page headings](#page-headings) + - [Sidebar](#sidebar) - [Title](#title) - [Headings](#headings) - [Text formatting](#text-formatting) @@ -30,7 +34,7 @@ This guide covers Markdown-specific syntax and formatting conventions used in Co - [Tables](#tables) - [Markdown tables](#markdown-tables) - [HTML tables](#html-tables) - - [Markdown vs HTML](#markdown-vs-html) + - [Markdown vs. HTML](#markdown-vs-html) - [Images](#images) - [Videos](#videos) - [Versioning](#versioning) @@ -46,6 +50,87 @@ This guide covers Markdown-specific syntax and formatting conventions used in Co - [Comments](#comments) - [TODOs](#todos) +## Site structure + +### Docs repository + +Documentation for each CockroachDB version is organized in dedicated directories. For example, CockroachDB v23.1 docs are in `src/current/v23.1` and `src/current/_includes/v23.1`, while CockroachDB API docs are in `src/api`. + +Each page must be a `.md` file written in [Redcarpet](https://github.com/vmg/redcarpet) Markdown. Use lowercase file names with dashes between words. + +**Example:** `name-of-your-file.md` + +### Page headings + +All Markdown pages require YAML front matter: + +```yaml +--- +title: Title of Page +summary: Short description of page for SEO +--- +``` + +**Required fields:** + +Field | Description +------|------------ +`title` | Page heading in title case +`summary` | SEO meta description (50-160 characters) + +**Optional fields:** + +Field | Description | Default +------|-------------|-------- +`toc` | Auto-generates page table of contents | `true` +`toc_not_nested` | Limits TOC to h2 headers only | `false` +`allowed_hashes` | URL hashes that don't correspond to headings | None +`feedback` | Adds Yes/No feedback buttons | `true` +`contribute` | Adds Contribute options | `true` +`twitter` | Enables Twitter campaign tracking | `false` +`no_sidebar` | Removes page sidebar | `false` +`block_search` | Excludes page from search indexing | `false` +`back_to_top` | Adds back-to-top button | `false` +`docs_area` | Analytics area (for example, `get_started`, `reference.sql`) | None +`product_area` | Product area for analytics | None + +### Sidebar + +Each CockroachDB version uses a JSON file to define sidebar navigation. The file is located at `_includes/vXX.Y/sidebar-data/{section}.json`. + +**JSON structure:** + +Field | Type | Description +------|------|------------ +`title` | String | Section or page title in sidebar +`items` | Array | Pages or subsections within a section +`urls` | Array | Page URLs formatted as `/${VERSION}/.html` + +**Example structure:** + +```json +[ + { + "title": "Get Started", + "items": [ + { + "title": "Install CockroachDB", + "urls": ["/${VERSION}/install-cockroachdb.html"] + }, + { + "title": "Start a Local Cluster", + "items": [ + { + "title": "From Binary", + "urls": ["/${VERSION}/start-a-local-cluster.html"] + } + ] + } + ] + } +] +``` + ## Title Set the page title in the `title:` metadata. The title should be in title case. Heading 1 (`#`) is reserved for page titles and **should not** be used in pages. @@ -118,7 +203,7 @@ When linking to a versioned page from a Technical Advisory (in `advisories`), ha ### Custom anchor links -To link to a specific location on a page that is not a heading (e.g., a specific command-line flag in a table), add a manual anchor and use the `id` parameter: +To link to a specific location on a page that is not a heading (for example, a specific command-line flag in a table), add a manual anchor and use the `id` parameter: **Example:** @@ -149,7 +234,7 @@ For websites that automatically localize pages, avoid using localization element ### Inline code -Use inline code when referring to code, commands, or other technical syntax within a sentence. Inline `code` is surrounded by backticks (``). +Use inline code when referring to code, commands, values, or other technical syntax within a sentence. Inline `code` is surrounded by backticks (``). **Example:** The `CREATE TABLE` statement creates a new table in a database. @@ -213,28 +298,11 @@ Notes for usage: - **Copy to Clipboard** should be used for every code block that can be **executed**. - To render properly, there must be a line break above the `{% include_cached copy-clipboard.html %}` line. -### Placeholders - -Code samples often include placeholder values, to be replaced by values specific to a user's environment. To denote that a value in a code sample is a placeholder value that should be replaced, use curly brackets (`{}`). - -For example: `SELECT * FROM TABLE {mytable};`. In this code sample, `{mytable}` would be replaced by some table name before the code could actually run. - -When you use placeholders, you usually need to define the value within the brackets, if the placeholder value isn't clear. Define placeholder values immediately following the code sample: - -- For a single placeholder value, use a follow-up sentence. -- For multiple placeholder values, use a bulleted list. -- For many placeholder values (10+), use a table. -- For large code blocks, define the placeholder values inside the code block with an inline code comment. - -Ensure that placeholders are placed within backticks: `SET {session variable}`. This signifies that placeholder values are code. - -If the code sample is sensitive to curly bracket characters (e.g., JavaScript), you can use `<>` instead. - ### Escaping special characters Sometimes you may need to escape special characters to achieve proper rendering: -- **Jekyll-reserved characters** (e.g., double `{{ ... }}`) in code blocks: Wrap the specific line(s) with Liquid tags `{% raw %} ... {% endraw %}`. +- **Jekyll-reserved characters** (for example, double `{{ ... }}`) in code blocks: Wrap the specific line(s) with Liquid tags `{% raw %} ... {% endraw %}`. ~~~markdown {% raw %}summary: Instance {{ $labels.instance }} has {{ $value }} tripped per-Replica circuit breakers{% endraw %} @@ -257,7 +325,7 @@ Introduce a list with a sentence and a colon. Use periods at the end of list ite ### Ordered lists -For each item of a **numbered list**, use `1.` followed by a period and a space, e.g., `1. This is a numbered list item`. The HTML renderer will render the steps in the correct order. +For each item of a **numbered list**, use `1.` followed by a period and a space, for example, `1. This is a numbered list item`. The HTML renderer will render the steps in the correct order. ~~~markdown 1. This is the first step. @@ -267,7 +335,7 @@ For each item of a **numbered list**, use `1.` followed by a period and a space, ### Unordered lists -For each item of a **bulleted list**, use one dash followed by one space, e.g., `- This is a bulleted list item`. +For each item of a **bulleted list**, use one dash followed by one space, for example, `- This is a bulleted list item`. ~~~markdown - This is a bullet point. @@ -343,7 +411,7 @@ Use tables to display structured information in an easy-to-read format. We use t ### Markdown tables -If you can keep the table formatting simple (e.g., basic text formatting and using `
` tags for paragraph breaks), create a table using Markdown. This is the preferred table format. +If you can keep the table formatting simple (for example, basic text formatting and using `
` tags for paragraph breaks), create a table using Markdown. This is the preferred table format. To create a table, use pipes (`|`) between columns and at least 3 dashes (`-`) separating the header cells from the body cells. A return denotes the start of the next row. The text within each column does not need to align in order to be rendered correctly, and you can inline Markdown or HTML. @@ -390,12 +458,40 @@ You can use the following HTML formatting within an HTML table: - Paragraph breaks (`

`) - Lists (`

    ` / `