# Markdown Extensions SolidBase provides multiple ways to extend markdown syntax from [GFM](https://github.github.com/gfm/) to fully customized ones. The following sections list all of their options and usage examples. ## Autolinked Titles Each title, heading, and subheading will automatically be given a unique slug and self link. ```md tab title="Markdown" # My Docs ## Subheading ``` ```html tab title="HTML Output"

My Docs

Subheading

``` ## External Links Each outbound link will automatically get `target="_blank" rel="noreferrer"` attributes for security and performance reasons. ```md tab title="Markdown" [SolidJS](https://www.solidjs.com) [SolidBase on GitHub](https://github.com/kobaltedev/solidbase) ``` ```html tab title="HTML Output" SolidJS SolidBase on GitHub ``` ## Frontmatter Out of the box, SolidBase supports [YAML frontmatter](https://mdxjs.com/guides/frontmatter/) to define metadata at the top of your markdown files. To add frontmatter to your markdown file, simply add a YAML block at the very top of the file, wrapped in triple dashes `---`. ```mdx title="Markdown" --- title: SolidBase layout: home --- # {frontmatter.title} ``` The data defined in the frontmatter will be parsed and made available to the page as a `frontmatter` object. It is made available through the entire application, including all custom and theming components. For more details, see the [Frontmatter reference](/reference/frontmatter). ## Table of Contents You can automatically generate a table of contents (ToC) for your markdown files by adding `[[toc]]` anywhere in the document. The ToC will be generated based on all titles, headings, and subheadings in the document. **Input** ``` [[toc]] ``` **Output** 1. [Markdown Extensions](#markdown-extensions) 1. [Autolinked Titles](#autolinked-titles) 2. [External Links](#external-links) 3. [Frontmatter](#frontmatter) 4. [Table of Contents](#table-of-contents) 5. [Directives](#directives) 1. [Custom Directive Titles](#custom-directive-titles) 6. [Tabs](#tabs) 7. [Previews](#previews) 8. [GitHub Flavored Markown](#github-flavored-markown) 1. [Alerts](#alerts) 2. [Autolinks](#autolinks) 3. [Tables](#tables) 4. [Task Lists](#task-lists) 5. [Horizontal Rules](#horizontal-rules) 9. [Footnotes](#footnotes) 10. [Code Blocks](#code-blocks) 1. [Line Highlighting](#line-highlighting) 2. [Line Numbers](#line-numbers) 3. [Code Tabs](#code-tabs) 4. [Twoslash](#twoslash) 11. [Collapsible](#collapsible) 12. [Advanced Configuration](#advanced-configuration) ## Directives Directives are custom blocks that can be used to highlight important information, warnings, tips, and more. They are similar to callouts or alerts in other documentation systems. :::::tab-group[features-demo-directives] :::tab[Markdown] ```md :::info Highlights information that users should take into account, even when skimming. ::: ``` ::: ::::tab[HTML Output] :::info Highlights information that users should take into account, even when skimming. ::: :::: ::::: :::::tab-group[features-demo-directives] :::tab[Markdown] ```md :::tip Optional information to help a user be more successful. ::: ``` ::: ::::tab[HTML Output] :::tip Optional information to help a user be more successful. ::: :::: ::::: :::::tab-group[features-demo-directives] :::tab[Markdown] ```md :::important Crucial information necessary for users to succeed. ::: ``` ::: ::::tab[HTML Output] :::important Crucial information necessary for users to succeed. ::: :::: ::::: :::::tab-group[features-demo-directives] :::tab[Markdown] ```md :::warning Critical content demanding immediate user attention due to potential risks. ::: ``` ::: ::::tab[HTML Output] :::warning Critical content demanding immediate user attention due to potential risks. ::: :::: ::::: :::::tab-group[features-demo-directives] :::tab[Markdown] ```md :::danger Negative potential consequences of an action. ::: ``` ::: ::::tab[HTML Output] :::danger Negative potential consequences of an action. ::: :::: ::::: :::::tab-group[features-demo-directives] :::tab[Markdown] ```md :::details This is a details block. ::: ``` ::: ::::tab[HTML Output] :::details This is a details block. ::: :::: ::::: ### Custom Directive Titles To set a custom title for a directive, use square brackets `[]` immediately after the directive type. :::::tab-group[features-demo-directives-titles] :::tab[Markdown] ```md :::info[Custom Title] Highlights information that users should take into account, even when skimming. ::: ``` ::: ::::tab[HTML Output] :::info[Custom Title] Highlights information that users should take into account, even when skimming. ::: :::: ::::: :::::tab-group[features-demo-directives-titles] :::tab[Markdown] ```md :::tip[] This is a tip with no title. ::: ``` ::: ::::tab[HTML Output] :::tip This is a tip with no title. ::: :::: ::::: :::::tab-group[features-demo-directives-titles] :::tab[Markdown] ```md :::details[Click me to view] This is a details block. ::: ``` ::: ::::tab[HTML Output] :::details[Click me to view] This is a details block. ::: :::: ::::: ## Tabs ::::::tab-group :::tab[Markdown] ```mdx ::::tab-group[key] :::tab[Title A] Hey I'm A ::: :::tab[Title B] Hi this is B ::: :::: ``` ::: :::::tab[HTML Output] ::::tab-group :::tab[Title A] Hey I'm A ::: :::tab[Title B] Hi this is B ::: :::: ::::: :::::: `[key]` is used for syncing and persistance. ## Previews Use the `preview` directive to show rendered content in a framed preview. For the full syntax and validation contract, see the [Preview Directive reference](/reference/preview-directive). ```mdx :::preview ::: ``` :::preview
Preview card Rendered MDX appears here.
::: Add a thematic break (`---`) to include a lower panel with supporting content. The lower panel can contain code tabs, prose, directives, or any other MDX content. ````mdx :::preview --- ```tsx tab title="index.tsx" export function PreviewCard() { return (
Preview card Rendered MDX appears here.
); } ``` ```css tab title="style.css" .preview-card { display: grid; gap: 0.35rem; padding: 1rem; border-radius: 0.75rem; } ``` ::: ```` :::preview
Preview card Rendered MDX appears here.
*** ```tsx tab title="index.tsx" export function PreviewCard() { return (
Preview card Rendered MDX appears here.
); } ``` ```css tab title="style.css" .preview-card { display: grid; gap: 0.35rem; padding: 1rem; border-radius: 0.75rem; } ``` ::: If a preview contains nested container directives, use a longer fence for the outer preview. This keeps the inner directive closing fence from closing the preview. ```mdx ::::preview --- :::tip Use a longer outer fence when the panel contains another directive. ::: :::: ``` ## GitHub Flavored Markown In addition to the standard markdown syntax, SolidBase also supports several GitHub Flavored Markdown (GFM) extensions. ### Alerts In addition to the directives above, SolidBase also supports [GitHub-flavored alerts](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts). These alerts can render as callouts with similar styles to the [directives above](#directives). :::::tab-group[features-demo-directives-gfm] :::tab[Markdown] ```md > [!NOTE] > Highlights information that users should take into account, even when skimming. ``` ::: ::::tab[HTML Output] :::note Highlights information that users should take into account, even when skimming. ::: :::: ::::: :::::tab-group[features-demo-directives-gfm] :::tab[Markdown] ```md > [!TIP] > Optional information to help a user be more successful. ``` ::: ::::tab[HTML Output] :::tip Optional information to help a user be more successful. ::: :::: ::::: :::::tab-group[features-demo-directives-gfm] :::tab[Markdown] ```md > [!IMPORTANT] > Crucial information necessary for users to succeed. ``` ::: ::::tab[HTML Output] :::important Crucial information necessary for users to succeed. ::: :::: ::::: :::::tab-group[features-demo-directives-gfm] :::tab[Markdown] ```md > [!WARNING] > Critical content demanding immediate user attention due to potential risks. ``` ::: ::::tab[HTML Output] :::warning Critical content demanding immediate user attention due to potential risks. ::: :::: ::::: :::::tab-group[features-demo-directives-gfm] :::tab[Markdown] ```md > [!CAUTION] > Negative potential consequences of an action. ``` ::: ::::tab[HTML Output] :::caution Negative potential consequences of an action. ::: :::: ::::: ### Autolinks SolidBase is able to automatically detect and convert URLs into clickable links. ::::tab-group :::tab[Markdown] ```md https://github.com/kobaltedev/solidbase ``` ::: :::tab[HTML Output] [https://github.com/kobaltedev/solidbase](https://github.com/kobaltedev/solidbase) ::: :::: ### Tables **Input** ```md | a | b | c | d | | -------- | :------- | -------: | :------: | | longword | longword | longword | longword | | short | short | short | `short` | ``` **Output** | a | b | c | d | | -------- | :------- | -------: | :------: | | longword | longword | longword | longword | | short | short | short | `short` | ### Task Lists **Input** ```md - [ ] to do - [x] done ``` **Output** * [ ] to do * [x] done ### Horizontal Rules You can create horizontal rules (or horizontal lines) through the following methods: * Three or more hyphens (`---`) * Three or more asterisks (`***`) * Three or more underscores (`___`) * HTML `
` tag ## Footnotes Footnotes are able to be added anywhere in the document using `[^label]` syntax, where `label` is a unique identifier for the footnote. To define the footnote content, the footnote definition should be placed at the end of the document, using the same `[^label]:` syntax followed by the footnote text. **Input** ```md A note[^1] [^1]: Big note. ``` **Output** A note[^1] [^1]: Big note. ## Code Blocks SolidBase uses [Expressive Code](https://expressive-code.com/) to highlight code blocks. Expressive Code is a fast and flexible syntax highlighter that supports a wide range of programming languages as well as additional features like line highlighting, line numbers, collapsible sections, code tabs, and more. The list of supported languages is [available on GitHub](https://github.com/antfu/textmate-grammars-themes/blob/main/packages/tm-grammars/README.md) To use Expressive Code, simply wrap your code in triple backticks (\`\`\`) and specify the language after the opening backticks. This will enable syntax highlighting for that language. **Input** ```` ```tsx export default function App() { return ( ); } ``` ```json { "data": { "values": 4 } } ``` ```` **Output** ```tsx export default function App() { return ; } ``` ```json { "data": { "values": 4 } } ``` ### Line Highlighting In addition to syntax highlighting, you can also highlight specific lines in a code block by adding curly braces `{}` after the language and specifying the line numbers or ranges you want to highlight. You can specify single lines (e.g., `{4}`), multiple single lines (e.g., `{4, 6, 10}`), line ranges (e.g., `{1-4}`), or a combination of both (e.g., `{4, 6-10, 15, 20-24, 40}`). **Input** ```` ```js {1, 4, 6-8} export default { // Highlighted data () { return { msg: "Highlighted!" other: "Not highlighted", f: `But we are`, } } } ``` ```` **Output** ```js {1, 4, 6-8} export default { // Highlighted data () { return { msg: "Highlighted!" other: "Not highlighted", f: `But we are`, } } } ``` ### Line Numbers By default, line numbers are disabled. To enable them, add `showLineNumbers` after the language. **Input** ````md ```ts showLineNumbers const line2 = "This is line 2"; const line3 = "This is line 3"; ``` ```` **Output** ```ts showLineNumbers const line2 = 'This is line 2' const line3 = 'This is line 3' ``` ### Code Tabs When you have multiple related code blocks, you can group them into tabs for better organization and readability. To create code tabs, add `tab` after the language and specify a `title` for each tab. **Input** ````md ```tsx {4} tab title="a.tsx" import { SolidBaseApp } from "@kobalte/solidbase"; export default function App() { return ; } ``` ```tsx {4} tab title="b.tsx" import { SolidBaseApp } from "@kobalte/solidbase"; export default function App() { return ; } ``` ```` **Output** ```tsx {4} tab title="a.tsx" import { SolidBaseApp } from "@kobalte/solidbase"; export default function App() { return ; } ``` ```tsx {4} tab title="b.tsx" import { SolidBaseApp } from "@kobalte/solidbase"; export default function App() { return ; } ``` ### Twoslash // TODO ## Collapsible // TODO ## Advanced Configuration // TODO