From 20cbf3b6a4d1598a62fdb176ebaa849bc7b978f7 Mon Sep 17 00:00:00 2001 From: HiDeoo Date: Sat, 7 Sep 2024 00:19:29 +0200 Subject: Add Markdoc preset and example (#2249) Co-authored-by: Chris Swithinbank <357379+delucis@users.noreply.github.com> Co-authored-by: Chris Swithinbank --- .changeset/selfish-chefs-tie.md | 7 + .github/labeler.yml | 3 + docs/src/content/docs/guides/authoring-content.md | 395 ---------------- docs/src/content/docs/guides/authoring-content.mdx | 510 +++++++++++++++++++++ docs/src/content/docs/guides/pages.mdx | 2 +- examples/markdoc/.gitignore | 21 + examples/markdoc/.vscode/extensions.json | 4 + examples/markdoc/.vscode/launch.json | 11 + examples/markdoc/README.md | 56 +++ examples/markdoc/astro.config.mjs | 29 ++ examples/markdoc/markdoc.config.mjs | 7 + examples/markdoc/package.json | 20 + examples/markdoc/public/favicon.svg | 1 + examples/markdoc/src/assets/houston.webp | Bin 0 -> 98506 bytes examples/markdoc/src/content/config.ts | 6 + .../markdoc/src/content/docs/guides/example.mdoc | 11 + examples/markdoc/src/content/docs/index.mdoc | 35 ++ .../src/content/docs/reference/example.mdoc | 11 + examples/markdoc/src/env.d.ts | 1 + examples/markdoc/tsconfig.json | 3 + packages/markdoc/.npmignore | 1 + packages/markdoc/Code.astro | 16 + packages/markdoc/README.md | 18 + packages/markdoc/__tests__/markdoc.test-d.ts | 127 +++++ packages/markdoc/components.ts | 1 + packages/markdoc/html.mjs | 44 ++ packages/markdoc/index.mjs | 264 +++++++++++ packages/markdoc/package.json | 26 ++ .../__tests__/basics/navigation-labels.test.ts | 2 +- .../__tests__/basics/navigation-order.test.ts | 2 +- .../starlight/__tests__/basics/navigation.test.ts | 2 +- .../__tests__/basics/pagination-with-base.test.ts | 2 +- .../starlight/__tests__/basics/routing.test.ts | 6 +- .../basics/starlight-page-route-data.test.ts | 2 +- .../__tests__/i18n-root-locale/routing.test.ts | 11 +- .../i18n-sidebar-fallback-slug.test.ts | 2 +- .../__tests__/i18n-sidebar/i18n-sidebar.test.ts | 2 +- .../sidebar-internal-link-error.test.ts | 2 +- .../i18n-single-root-locale/routing.test.ts | 2 +- pnpm-lock.yaml | 101 +++- 40 files changed, 1349 insertions(+), 417 deletions(-) create mode 100644 .changeset/selfish-chefs-tie.md delete mode 100644 docs/src/content/docs/guides/authoring-content.md create mode 100644 docs/src/content/docs/guides/authoring-content.mdx create mode 100644 examples/markdoc/.gitignore create mode 100644 examples/markdoc/.vscode/extensions.json create mode 100644 examples/markdoc/.vscode/launch.json create mode 100644 examples/markdoc/README.md create mode 100644 examples/markdoc/astro.config.mjs create mode 100644 examples/markdoc/markdoc.config.mjs create mode 100644 examples/markdoc/package.json create mode 100644 examples/markdoc/public/favicon.svg create mode 100644 examples/markdoc/src/assets/houston.webp create mode 100644 examples/markdoc/src/content/config.ts create mode 100644 examples/markdoc/src/content/docs/guides/example.mdoc create mode 100644 examples/markdoc/src/content/docs/index.mdoc create mode 100644 examples/markdoc/src/content/docs/reference/example.mdoc create mode 100644 examples/markdoc/src/env.d.ts create mode 100644 examples/markdoc/tsconfig.json create mode 100644 packages/markdoc/.npmignore create mode 100644 packages/markdoc/Code.astro create mode 100644 packages/markdoc/README.md create mode 100644 packages/markdoc/__tests__/markdoc.test-d.ts create mode 100644 packages/markdoc/components.ts create mode 100644 packages/markdoc/html.mjs create mode 100644 packages/markdoc/index.mjs create mode 100644 packages/markdoc/package.json diff --git a/.changeset/selfish-chefs-tie.md b/.changeset/selfish-chefs-tie.md new file mode 100644 index 00000000..f8869194 --- /dev/null +++ b/.changeset/selfish-chefs-tie.md @@ -0,0 +1,7 @@ +--- +'@astrojs/starlight-markdoc': minor +--- + +Adds Starlight Markdoc preset. + +See the [“Markdoc”](https://starlight.astro.build/guides/authoring-content/#markdoc) guide to learn more on how to use this preset in a new or existing project. diff --git a/.github/labeler.yml b/.github/labeler.yml index 6049ae3c..4913a2e0 100644 --- a/.github/labeler.yml +++ b/.github/labeler.yml @@ -26,5 +26,8 @@ i18n: '🌟 tailwind': - packages/tailwind/** +'🌟 markdoc': + - packages/markdoc/** + '📚 docs': - docs/** diff --git a/docs/src/content/docs/guides/authoring-content.md b/docs/src/content/docs/guides/authoring-content.md deleted file mode 100644 index 2fe84815..00000000 --- a/docs/src/content/docs/guides/authoring-content.md +++ /dev/null @@ -1,395 +0,0 @@ ---- -title: Authoring Content in Markdown -description: An overview of the Markdown syntax Starlight supports. ---- - -Starlight supports the full range of [Markdown](https://daringfireball.net/projects/markdown/) syntax in `.md` files as well as frontmatter [YAML](https://dev.to/paulasantamaria/introduction-to-yaml-125f) to define metadata such as a title and description. - -Please be sure to check the [MDX docs](https://mdxjs.com/docs/what-is-mdx/#markdown) or [Markdoc docs](https://markdoc.dev/docs/syntax) if using those file formats, as Markdown support and usage can differ. - -## Frontmatter - -You can customize individual pages in Starlight by setting values in their frontmatter. -Frontmatter is set at the top of your files between `---` separators: - -```md title="src/content/docs/example.md" ---- -title: My page title ---- - -Page content follows the second `---`. -``` - -Every page must include at least a `title`. -See the [frontmatter reference](/reference/frontmatter/) for all available fields and how to add custom fields. - -## Inline styles - -Text can be **bold**, _italic_, or ~~strikethrough~~. - -```md -Text can be **bold**, _italic_, or ~~strikethrough~~. -``` - -You can [link to another page](/getting-started/). - -```md -You can [link to another page](/getting-started/). -``` - -You can highlight `inline code` with backticks. - -```md -You can highlight `inline code` with backticks. -``` - -## Images - -Images in Starlight use [Astro’s built-in optimized asset support](https://docs.astro.build/en/guides/assets/). - -Markdown and MDX support the Markdown syntax for displaying images that includes alt-text for screen readers and assistive technology. - -![An illustration of planets and stars featuring the word “astro”](https://raw.githubusercontent.com/withastro/docs/main/public/default-og-image.png) - -```md -![An illustration of planets and stars featuring the word “astro”](https://raw.githubusercontent.com/withastro/docs/main/public/default-og-image.png) -``` - -Relative image paths are also supported for images stored locally in your project. - -```md -// src/content/docs/page-1.md - -![A rocketship in space](../../assets/images/rocket.svg) -``` - -## Headings - -You can structure content using a heading. Headings in Markdown are indicated by a number of `#` at the start of the line. - -### How to structure page content in Starlight - -Starlight is configured to automatically use your page title as a top-level heading and will include an "Overview" heading at top of each page's table of contents. We recommend starting each page with regular paragraph text content and using on-page headings from `

` and down: - -```md ---- -title: Markdown Guide -description: How to use Markdown in Starlight ---- - -This page describes how to use Markdown in Starlight. - -## Inline Styles - -## Headings -``` - -### Automatic heading anchor links - -Using headings in Markdown will automatically give you anchor links so you can link directly to certain sections of your page: - -```md ---- -title: My page of content -description: How to use Starlight's built-in anchor links ---- - -## Introduction - -I can link to [my conclusion](#conclusion) lower on the same page. - -## Conclusion - -`https://my-site.com/page1/#introduction` navigates directly to my Introduction. -``` - -Level 2 (`

`) and Level 3 (`

`) headings will automatically appear in the page table of contents. - -Learn more about how Astro processes heading `id`s in [the Astro Documentation](https://docs.astro.build/en/guides/markdown-content/#heading-ids) - -## Asides - -Asides (also known as “admonitions” or “callouts”) are useful for displaying secondary information alongside a page’s main content. - -Starlight provides a custom Markdown syntax for rendering asides. Aside blocks are indicated using a pair of triple colons `:::` to wrap your content, and can be of type `note`, `tip`, `caution` or `danger`. - -You can nest any other Markdown content types inside an aside, but asides are best suited to short and concise chunks of content. - -### Note aside - -:::note -Starlight is a documentation website toolkit built with [Astro](https://astro.build/). You can get started with this command: - -```sh -npm create astro@latest -- --template starlight -``` - -::: - -````md -:::note -Starlight is a documentation website toolkit built with [Astro](https://astro.build/). You can get started with this command: - -```sh -npm create astro@latest -- --template starlight -``` - -::: -```` - -### Custom aside titles - -You can specify a custom title for the aside in square brackets following the aside type, e.g. `:::tip[Did you know?]`. - -:::tip[Did you know?] -Astro helps you build faster websites with [“Islands Architecture”](https://docs.astro.build/en/concepts/islands/). -::: - -```md -:::tip[Did you know?] -Astro helps you build faster websites with [“Islands Architecture”](https://docs.astro.build/en/concepts/islands/). -::: -``` - -### More aside types - -Caution and danger asides are helpful for drawing a user’s attention to details that may trip them up. -If you find yourself using these a lot, it may also be a sign that the thing you are documenting could benefit from being redesigned. - -:::caution -If you are not sure you want an awesome docs site, think twice before using [Starlight](/). -::: - -:::danger -Your users may be more productive and find your product easier to use thanks to helpful Starlight features. - -- Clear navigation -- User-configurable colour theme -- [i18n support](/guides/i18n/) - -::: - -```md -:::caution -If you are not sure you want an awesome docs site, think twice before using [Starlight](/). -::: - -:::danger -Your users may be more productive and find your product easier to use thanks to helpful Starlight features. - -- Clear navigation -- User-configurable colour theme -- [i18n support](/guides/i18n/) - -::: -``` - -## Blockquotes - -> This is a blockquote, which is commonly used when quoting another person or document. -> -> Blockquotes are indicated by a `>` at the start of each line. - -```md -> This is a blockquote, which is commonly used when quoting another person or document. -> -> Blockquotes are indicated by a `>` at the start of each line. -``` - -## Code blocks - -A code block is indicated by a block with three backticks ``` at the start and end. You can indicate the programming language being used after the opening backticks. - -```js -// Javascript code with syntax highlighting. -var fun = function lang(l) { - dateformat.i18n = require('./lang/' + l); - return true; -}; -``` - -````md -```js -// Javascript code with syntax highlighting. -var fun = function lang(l) { - dateformat.i18n = require('./lang/' + l); - return true; -}; -``` -```` - -### Expressive Code features - -Starlight uses [Expressive Code](https://github.com/expressive-code/expressive-code/tree/main/packages/astro-expressive-code) to extend formatting possibilities for code blocks. -Expressive Code’s text markers and window frames plugins are enabled by default. -Code block rendering can be configured using Starlight’s [`expressiveCode` configuration option](/reference/configuration/#expressivecode). - -#### Text markers - -You can highlight specific lines or parts of your code blocks using [Expressive Code text markers](https://github.com/expressive-code/expressive-code/blob/main/packages/%40expressive-code/plugin-text-markers/README.md#usage-in-markdown--mdx-documents) on the opening line of your code block. -Use curly braces (`{ }`) to highlight entire lines, and quotation marks to highlight strings of text. - -There are three highlighting styles: neutral for calling attention to code, green for indicating inserted code, and red for indicating deleted code. -Both text and entire lines can be marked using the default marker, or in combination with `ins=` and `del=` to produce the desired highlighting. - -Expressive Code provides several options for customizing the visual appearance of your code samples. -Many of these can be combined, for highly illustrative code samples. -Please explore the [Expressive Code documentation](https://github.com/expressive-code/expressive-code/blob/main/packages/%40expressive-code/plugin-text-markers/README.md) for the extensive options available. -Some of the most common examples are shown below: - -- [Mark entire lines & line ranges using the `{ }` marker](https://github.com/expressive-code/expressive-code/blob/main/packages/%40expressive-code/plugin-text-markers/README.md#marking-entire-lines--line-ranges): - - ```js {2-3} - function demo() { - // This line (#2) and the next one are highlighted - return 'This is line #3 of this snippet'; - } - ``` - - ````md - ```js {2-3} - function demo() { - // This line (#2) and the next one are highlighted - return 'This is line #3 of this snippet'; - } - ``` - ```` - -- [Mark selections of text using the `" "` marker or regular expressions](https://github.com/expressive-code/expressive-code/blob/main/packages/%40expressive-code/plugin-text-markers/README.md#marking-individual-text-inside-lines): - - ```js "Individual terms" /Even.*supported/ - // Individual terms can be highlighted, too - function demo() { - return 'Even regular expressions are supported'; - } - ``` - - ````md - ```js "Individual terms" /Even.*supported/ - // Individual terms can be highlighted, too - function demo() { - return 'Even regular expressions are supported'; - } - ``` - ```` - -- [Mark text or lines as inserted or deleted with `ins` or `del`](https://github.com/expressive-code/expressive-code/blob/main/packages/%40expressive-code/plugin-text-markers/README.md#selecting-marker-types-mark-ins-del): - - ```js "return true;" ins="inserted" del="deleted" - function demo() { - console.log('These are inserted and deleted marker types'); - // The return statement uses the default marker type - return true; - } - ``` - - ````md - ```js "return true;" ins="inserted" del="deleted" - function demo() { - console.log('These are inserted and deleted marker types'); - // The return statement uses the default marker type - return true; - } - ``` - ```` - -- [Combine syntax highlighting with `diff`-like syntax](https://github.com/expressive-code/expressive-code/blob/main/packages/%40expressive-code/plugin-text-markers/README.md#combining-syntax-highlighting-with-diff-like-syntax): - - ```diff lang="js" - function thisIsJavaScript() { - // This entire block gets highlighted as JavaScript, - // and we can still add diff markers to it! - - console.log('Old code to be removed') - + console.log('New and shiny code!') - } - ``` - - ````md - ```diff lang="js" - function thisIsJavaScript() { - // This entire block gets highlighted as JavaScript, - // and we can still add diff markers to it! - - console.log('Old code to be removed') - + console.log('New and shiny code!') - } - ``` - ```` - -#### Frames and titles - -Code blocks can be rendered inside a window-like frame. -A frame that looks like a terminal window will be used for shell scripting languages (e.g. `bash` or `sh`). -Other languages display inside a code editor-style frame if they include a title. - -A code block’s optional title can be set either with a `title="..."` attribute following the code block's opening backticks and language identifier, or with a file name comment in the first lines of the code. - -- [Add a file name tab with a comment](https://github.com/expressive-code/expressive-code/blob/main/packages/%40expressive-code/plugin-frames/README.md#adding-titles-open-file-tab-or-terminal-window-title) - - ```js - // my-test-file.js - console.log('Hello World!'); - ``` - - ````md - ```js - // my-test-file.js - console.log('Hello World!'); - ``` - ```` - -- [Add a title to a Terminal window](https://github.com/expressive-code/expressive-code/blob/main/packages/%40expressive-code/plugin-frames/README.md#adding-titles-open-file-tab-or-terminal-window-title) - - ```bash title="Installing dependencies…" - npm install - ``` - - ````md - ```bash title="Installing dependencies…" - npm install - ``` - ```` - -- [Disable window frames with `frame="none"`](https://github.com/expressive-code/expressive-code/blob/main/packages/%40expressive-code/plugin-frames/README.md#overriding-frame-types) - - ```bash frame="none" - echo "This is not rendered as a terminal despite using the bash language" - ``` - - ````md - ```bash frame="none" - echo "This is not rendered as a terminal despite using the bash language" - ``` - ```` - -## Details - -Details (also known as “disclosures” or “accordions”) are useful to hide content that is not immediately relevant. -Users can click a short summary to expand and view the full content. - -Use the standard HTML [`
`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details) and [``](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/summary) elements in your Markdown content to create a disclosure widget. - -You can nest any other Markdown syntax inside a `
` element. - -
-Where and when is the Andromeda constellation most visible? - -The [Andromeda constellation]() is most visible in the night sky during the month of November at latitudes between `+90°` and `−40°`. - -
- -```md -
-Where and when is the Andromeda constellation most visible? - -The [Andromeda constellation]() is most visible in the night sky during the month of November at latitudes between `+90°` and `−40°`. - -
-``` - -## Other common Markdown features - -Starlight supports all other Markdown authoring syntax, such as lists and tables. See the [Markdown Cheat Sheet from The Markdown Guide](https://www.markdownguide.org/cheat-sheet/) for a quick overview of all the Markdown syntax elements. - -## Advanced Markdown and MDX configuration - -Starlight uses Astro’s Markdown and MDX renderer built on remark and rehype. You can add support for custom syntax and behavior by adding `remarkPlugins` or `rehypePlugins` in your Astro config file. See [“Configuring Markdown and MDX”](https://docs.astro.build/en/guides/markdown-content/#configuring-markdown-and-mdx) in the Astro docs to learn more. diff --git a/docs/src/content/docs/guides/authoring-content.mdx b/docs/src/content/docs/guides/authoring-content.mdx new file mode 100644 index 00000000..58c6f081 --- /dev/null +++ b/docs/src/content/docs/guides/authoring-content.mdx @@ -0,0 +1,510 @@ +--- +title: Authoring Content in Markdown +description: An overview of the Markdown syntax Starlight supports. +--- + +Starlight supports the full range of [Markdown](https://daringfireball.net/projects/markdown/) syntax in `.md` files as well as frontmatter [YAML](https://dev.to/paulasantamaria/introduction-to-yaml-125f) to define metadata such as a title and description. + +Please be sure to check the [MDX docs](https://mdxjs.com/docs/what-is-mdx/#markdown) or [Markdoc docs](https://markdoc.dev/docs/syntax) if using those file formats, as Markdown support and usage can differ. + +## Frontmatter + +You can customize individual pages in Starlight by setting values in their frontmatter. +Frontmatter is set at the top of your files between `---` separators: + +```md title="src/content/docs/example.md" +--- +title: My page title +--- + +Page content follows the second `---`. +``` + +Every page must include at least a `title`. +See the [frontmatter reference](/reference/frontmatter/) for all available fields and how to add custom fields. + +## Inline styles + +Text can be **bold**, _italic_, or ~~strikethrough~~. + +```md +Text can be **bold**, _italic_, or ~~strikethrough~~. +``` + +You can [link to another page](/getting-started/). + +```md +You can [link to another page](/getting-started/). +``` + +You can highlight `inline code` with backticks. + +```md +You can highlight `inline code` with backticks. +``` + +## Images + +Images in Starlight use [Astro’s built-in optimized asset support](https://docs.astro.build/en/guides/assets/). + +Markdown and MDX support the Markdown syntax for displaying images that includes alt-text for screen readers and assistive technology. + +![An illustration of planets and stars featuring the word “astro”](https://raw.githubusercontent.com/withastro/docs/main/public/default-og-image.png) + +```md +![An illustration of planets and stars featuring the word “astro”](https://raw.githubusercontent.com/withastro/docs/main/public/default-og-image.png) +``` + +Relative image paths are also supported for images stored locally in your project. + +```md +// src/content/docs/page-1.md + +![A rocketship in space](../../assets/images/rocket.svg) +``` + +## Headings + +You can structure content using a heading. Headings in Markdown are indicated by a number of `#` at the start of the line. + +### How to structure page content in Starlight + +Starlight is configured to automatically use your page title as a top-level heading and will include an "Overview" heading at top of each page's table of contents. We recommend starting each page with regular paragraph text content and using on-page headings from `

` and down: + +```md +--- +title: Markdown Guide +description: How to use Markdown in Starlight +--- + +This page describes how to use Markdown in Starlight. + +## Inline Styles + +## Headings +``` + +### Automatic heading anchor links + +Using headings in Markdown will automatically give you anchor links so you can link directly to certain sections of your page: + +```md +--- +title: My page of content +description: How to use Starlight's built-in anchor links +--- + +## Introduction + +I can link to [my conclusion](#conclusion) lower on the same page. + +## Conclusion + +`https://my-site.com/page1/#introduction` navigates directly to my Introduction. +``` + +Level 2 (`

`) and Level 3 (`

`) headings will automatically appear in the page table of contents. + +Learn more about how Astro processes heading `id`s in [the Astro Documentation](https://docs.astro.build/en/guides/markdown-content/#heading-ids) + +## Asides + +Asides (also known as “admonitions” or “callouts”) are useful for displaying secondary information alongside a page’s main content. + +Starlight provides a custom Markdown syntax for rendering asides. Aside blocks are indicated using a pair of triple colons `:::` to wrap your content, and can be of type `note`, `tip`, `caution` or `danger`. + +You can nest any other Markdown content types inside an aside, but asides are best suited to short and concise chunks of content. + +### Note aside + +:::note +Starlight is a documentation website toolkit built with [Astro](https://astro.build/). You can get started with this command: + +```sh +npm create astro@latest -- --template starlight +``` + +::: + +````md +:::note +Starlight is a documentation website toolkit built with [Astro](https://astro.build/). You can get started with this command: + +```sh +npm create astro@latest -- --template starlight +``` + +::: +```` + +### Custom aside titles + +You can specify a custom title for the aside in square brackets following the aside type, e.g. `:::tip[Did you know?]`. + +:::tip[Did you know?] +Astro helps you build faster websites with [“Islands Architecture”](https://docs.astro.build/en/concepts/islands/). +::: + +```md +:::tip[Did you know?] +Astro helps you build faster websites with [“Islands Architecture”](https://docs.astro.build/en/concepts/islands/). +::: +``` + +### More aside types + +Caution and danger asides are helpful for drawing a user’s attention to details that may trip them up. +If you find yourself using these a lot, it may also be a sign that the thing you are documenting could benefit from being redesigned. + +:::caution +If you are not sure you want an awesome docs site, think twice before using [Starlight](/). +::: + +:::danger +Your users may be more productive and find your product easier to use thanks to helpful Starlight features. + +- Clear navigation +- User-configurable colour theme +- [i18n support](/guides/i18n/) + +::: + +```md +:::caution +If you are not sure you want an awesome docs site, think twice before using [Starlight](/). +::: + +:::danger +Your users may be more productive and find your product easier to use thanks to helpful Starlight features. + +- Clear navigation +- User-configurable colour theme +- [i18n support](/guides/i18n/) + +::: +``` + +## Blockquotes + +> This is a blockquote, which is commonly used when quoting another person or document. +> +> Blockquotes are indicated by a `>` at the start of each line. + +```md +> This is a blockquote, which is commonly used when quoting another person or document. +> +> Blockquotes are indicated by a `>` at the start of each line. +``` + +## Code blocks + +A code block is indicated by a block with three backticks ``` at the start and end. You can indicate the programming language being used after the opening backticks. + +```js +// Javascript code with syntax highlighting. +var fun = function lang(l) { + dateformat.i18n = require('./lang/' + l); + return true; +}; +``` + +````md +```js +// Javascript code with syntax highlighting. +var fun = function lang(l) { + dateformat.i18n = require('./lang/' + l); + return true; +}; +``` +```` + +### Expressive Code features + +Starlight uses [Expressive Code](https://github.com/expressive-code/expressive-code/tree/main/packages/astro-expressive-code) to extend formatting possibilities for code blocks. +Expressive Code’s text markers and window frames plugins are enabled by default. +Code block rendering can be configured using Starlight’s [`expressiveCode` configuration option](/reference/configuration/#expressivecode). + +#### Text markers + +You can highlight specific lines or parts of your code blocks using [Expressive Code text markers](https://github.com/expressive-code/expressive-code/blob/main/packages/%40expressive-code/plugin-text-markers/README.md#usage-in-markdown--mdx-documents) on the opening line of your code block. +Use curly braces (`{ }`) to highlight entire lines, and quotation marks to highlight strings of text. + +There are three highlighting styles: neutral for calling attention to code, green for indicating inserted code, and red for indicating deleted code. +Both text and entire lines can be marked using the default marker, or in combination with `ins=` and `del=` to produce the desired highlighting. + +Expressive Code provides several options for customizing the visual appearance of your code samples. +Many of these can be combined, for highly illustrative code samples. +Please explore the [Expressive Code documentation](https://github.com/expressive-code/expressive-code/blob/main/packages/%40expressive-code/plugin-text-markers/README.md) for the extensive options available. +Some of the most common examples are shown below: + +- [Mark entire lines & line ranges using the `{ }` marker](https://github.com/expressive-code/expressive-code/blob/main/packages/%40expressive-code/plugin-text-markers/README.md#marking-entire-lines--line-ranges): + + ```js {2-3} + function demo() { + // This line (#2) and the next one are highlighted + return 'This is line #3 of this snippet'; + } + ``` + + ````md + ```js {2-3} + function demo() { + // This line (#2) and the next one are highlighted + return 'This is line #3 of this snippet'; + } + ``` + ```` + +- [Mark selections of text using the `" "` marker or regular expressions](https://github.com/expressive-code/expressive-code/blob/main/packages/%40expressive-code/plugin-text-markers/README.md#marking-individual-text-inside-lines): + + ```js "Individual terms" /Even.*supported/ + // Individual terms can be highlighted, too + function demo() { + return 'Even regular expressions are supported'; + } + ``` + + ````md + ```js "Individual terms" /Even.*supported/ + // Individual terms can be highlighted, too + function demo() { + return 'Even regular expressions are supported'; + } + ``` + ```` + +- [Mark text or lines as inserted or deleted with `ins` or `del`](https://github.com/expressive-code/expressive-code/blob/main/packages/%40expressive-code/plugin-text-markers/README.md#selecting-marker-types-mark-ins-del): + + ```js "return true;" ins="inserted" del="deleted" + function demo() { + console.log('These are inserted and deleted marker types'); + // The return statement uses the default marker type + return true; + } + ``` + + ````md + ```js "return true;" ins="inserted" del="deleted" + function demo() { + console.log('These are inserted and deleted marker types'); + // The return statement uses the default marker type + return true; + } + ``` + ```` + +- [Combine syntax highlighting with `diff`-like syntax](https://github.com/expressive-code/expressive-code/blob/main/packages/%40expressive-code/plugin-text-markers/README.md#combining-syntax-highlighting-with-diff-like-syntax): + + ```diff lang="js" + function thisIsJavaScript() { + // This entire block gets highlighted as JavaScript, + // and we can still add diff markers to it! + - console.log('Old code to be removed') + + console.log('New and shiny code!') + } + ``` + + ````md + ```diff lang="js" + function thisIsJavaScript() { + // This entire block gets highlighted as JavaScript, + // and we can still add diff markers to it! + - console.log('Old code to be removed') + + console.log('New and shiny code!') + } + ``` + ```` + +#### Frames and titles + +Code blocks can be rendered inside a window-like frame. +A frame that looks like a terminal window will be used for shell scripting languages (e.g. `bash` or `sh`). +Other languages display inside a code editor-style frame if they include a title. + +A code block’s optional title can be set either with a `title="..."` attribute following the code block's opening backticks and language identifier, or with a file name comment in the first lines of the code. + +- [Add a file name tab with a comment](https://github.com/expressive-code/expressive-code/blob/main/packages/%40expressive-code/plugin-frames/README.md#adding-titles-open-file-tab-or-terminal-window-title) + + ```js + // my-test-file.js + console.log('Hello World!'); + ``` + + ````md + ```js + // my-test-file.js + console.log('Hello World!'); + ``` + ```` + +- [Add a title to a Terminal window](https://github.com/expressive-code/expressive-code/blob/main/packages/%40expressive-code/plugin-frames/README.md#adding-titles-open-file-tab-or-terminal-window-title) + + ```bash title="Installing dependencies…" + npm install + ``` + + ````md + ```bash title="Installing dependencies…" + npm install + ``` + ```` + +- [Disable window frames with `frame="none"`](https://github.com/expressive-code/expressive-code/blob/main/packages/%40expressive-code/plugin-frames/README.md#overriding-frame-types) + + ```bash frame="none" + echo "This is not rendered as a terminal despite using the bash language" + ``` + + ````md + ```bash frame="none" + echo "This is not rendered as a terminal despite using the bash language" + ``` + ```` + +## Details + +Details (also known as “disclosures” or “accordions”) are useful to hide content that is not immediately relevant. +Users can click a short summary to expand and view the full content. + +Use the standard HTML [`
`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details) and [``](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/summary) elements in your Markdown content to create a disclosure widget. + +You can nest any other Markdown syntax inside a `
` element. + +
+Where and when is the Andromeda constellation most visible? + +The [Andromeda constellation]() is most visible in the night sky during the month of November at latitudes between `+90°` and `−40°`. + +
+ +```md +
+Where and when is the Andromeda constellation most visible? + +The [Andromeda constellation]() is most visible in the night sky during the month of November at latitudes between `+90°` and `−40°`. + +
+``` + +## Other common Markdown features + +Starlight supports all other Markdown authoring syntax, such as lists and tables. See the [Markdown Cheat Sheet from The Markdown Guide](https://www.markdownguide.org/cheat-sheet/) for a quick overview of all the Markdown syntax elements. + +## Advanced Markdown and MDX configuration + +Starlight uses Astro’s Markdown and MDX renderer built on remark and rehype. You can add support for custom syntax and behavior by adding `remarkPlugins` or `rehypePlugins` in your Astro config file. See [“Configuring Markdown and MDX”](https://docs.astro.build/en/guides/markdown-content/#configuring-markdown-and-mdx) in the Astro docs to learn more. + +## Markdoc + +Starlight supports authoring content in Markdoc using the experimental [Astro Markdoc integration](https://docs.astro.build/en/guides/integrations-guide/markdoc/) and the Starlight Markdoc preset. + +### Create a new project with Markdoc + +Start a new Starlight project with Markdoc pre-configured using `create astro`: + +import { Tabs, TabItem, Steps } from '@astrojs/starlight/components'; + + + + +```sh +npm create astro@latest -- --template starlight/markdoc +``` + + + + +```sh +pnpm create astro --template starlight/markdoc +``` + + + + +```sh +yarn create astro --template starlight/markdoc +``` + + + + +### Add Markdoc to an existing project + +If you already have a Starlight site and want to add Markdoc, follow these steps. + + + +1. Add Astro’s Markdoc integration: + + + + + + ```sh + npx astro add markdoc + ``` + + + + + + ```sh + pnpm astro add markdoc + ``` + + + + + + ```sh + yarn astro add markdoc + ``` + + + + + +2. Install the Starlight Markdoc preset: + + + + + + ```sh + npm install @astrojs/starlight-markdoc + ``` + + + + + + ```sh + pnpm add @astrojs/starlight-markdoc + ``` + + + + + + ```sh + yarn add @astrojs/starlight-markdoc + ``` + + + + + +3. Create a Markdoc configuration file at `markdoc.config.mjs` and use the Starlight Markdoc preset: + + ```js + import { defineMarkdocConfig } from '@astrojs/markdoc/config'; + import starlightMarkdoc from '@astrojs/starlight-markdoc'; + + export default defineMarkdocConfig({ + extends: [starlightMarkdoc()], + }); + ``` + + + +To learn more about the Markdoc syntax and features, see the [Markdoc documentation](https://markdoc.dev/docs/syntax) or the [Astro Markdoc integration guide](https://docs.astro.build/en/guides/integrations-guide/markdoc/). diff --git a/docs/src/content/docs/guides/pages.mdx b/docs/src/content/docs/guides/pages.mdx index f112a572..663bea68 100644 --- a/docs/src/content/docs/guides/pages.mdx +++ b/docs/src/content/docs/guides/pages.mdx @@ -14,7 +14,7 @@ This guide shows how page generation works in Starlight. ### File formats Starlight supports authoring content in Markdown and MDX with no configuration required. -You can add support for Markdoc by installing the experimental [Astro Markdoc integration](https://docs.astro.build/en/guides/integrations-guide/markdoc/). +You can add support for Markdoc by following the [“Markdoc” guide](/guides/authoring-content/#markdoc). ### Add pages diff --git a/examples/markdoc/.gitignore b/examples/markdoc/.gitignore new file mode 100644 index 00000000..6240da8b --- /dev/null +++ b/examples/markdoc/.gitignore @@ -0,0 +1,21 @@ +# build output +dist/ +# generated types +.astro/ + +# dependencies +node_modules/ + +# logs +npm-debug.log* +yarn-debug.log* +yarn-error.log* +pnpm-debug.log* + + +# environment variables +.env +.env.production + +# macOS-specific files +.DS_Store diff --git a/examples/markdoc/.vscode/extensions.json b/examples/markdoc/.vscode/extensions.json new file mode 100644 index 00000000..a83595b1 --- /dev/null +++ b/examples/markdoc/.vscode/extensions.json @@ -0,0 +1,4 @@ +{ + "recommendations": ["astro-build.astro-vscode", "stripe.markdoc-language-support"], + "unwantedRecommendations": [] +} diff --git a/examples/markdoc/.vscode/launch.json b/examples/markdoc/.vscode/launch.json new file mode 100644 index 00000000..d6422097 --- /dev/null +++ b/examples/markdoc/.vscode/launch.json @@ -0,0 +1,11 @@ +{ + "version": "0.2.0", + "configurations": [ + { + "command": "./node_modules/.bin/astro dev", + "name": "Development server", + "request": "launch", + "type": "node-terminal" + } + ] +} diff --git a/examples/markdoc/README.md b/examples/markdoc/README.md new file mode 100644 index 00000000..584fd88e --- /dev/null +++ b/examples/markdoc/README.md @@ -0,0 +1,56 @@ +# Starlight Starter Kit: Markdoc + +[![Built with Starlight](https://astro.badg.es/v2/built-with-starlight/tiny.svg)](https://starlight.astro.build) + +``` +npm create astro@latest -- --template starlight/markdoc +``` + +[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/withastro/starlight/tree/main/examples/markdoc) +[![Open with CodeSandbox](https://assets.codesandbox.io/github/button-edit-lime.svg)](https://codesandbox.io/p/sandbox/github/withastro/starlight/tree/main/examples/markdoc) +[![Deploy to Netlify](https://www.netlify.com/img/deploy/button.svg)](https://app.netlify.com/start/deploy?repository=https://github.com/withastro/starlight&create_from_path=examples/markdoc) +[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fwithastro%2Fstarlight%2Ftree%2Fmain%2Fexamples%2Fmarkdoc&project-name=my-starlight-docs&repository-name=my-starlight-docs) + +> 🧑‍🚀 **Seasoned astronaut?** Delete this file. Have fun! + +## 🚀 Project Structure + +Inside of your Astro + Starlight project, you'll see the following folders and files: + +``` +. +├── public/ +├── src/ +│ ├── assets/ +│ ├── content/ +│ │ ├── docs/ +│ │ └── config.ts +│ └── env.d.ts +├── astro.config.mjs +├── markdoc.config.mjs +├── package.json +└── tsconfig.json +``` + +Starlight looks for `.md`, `.mdx` or `.mdoc` files in the `src/content/docs/` directory. Each file is exposed as a route based on its file name. + +Images can be added to `src/assets/` and embedded in Markdown with a relative link. + +Static assets, like favicons, can be placed in the `public/` directory. + +## 🧞 Commands + +All commands are run from the root of the project, from a terminal: + +| Command | Action | +| :------------------------ | :----------------------------------------------- | +| `npm install` | Installs dependencies | +| `npm run dev` | Starts local dev server at `localhost:4321` | +| `npm run build` | Build your production site to `./dist/` | +| `npm run preview` | Preview your build locally, before deploying | +| `npm run astro ...` | Run CLI commands like `astro add`, `astro check` | +| `npm run astro -- --help` | Get help using the Astro CLI | + +## 👀 Want to learn more? + +Check out [Starlight’s docs](https://starlight.astro.build/), read [the Astro documentation](https://docs.astro.build), or jump into the [Astro Discord server](https://astro.build/chat). diff --git a/examples/markdoc/astro.config.mjs b/examples/markdoc/astro.config.mjs new file mode 100644 index 00000000..03155ce5 --- /dev/null +++ b/examples/markdoc/astro.config.mjs @@ -0,0 +1,29 @@ +import { defineConfig } from 'astro/config'; +import starlight from '@astrojs/starlight'; +import markdoc from '@astrojs/markdoc'; + +// https://astro.build/config +export default defineConfig({ + integrations: [ + markdoc(), + starlight({ + title: 'My Docs', + social: { + github: 'https://github.com/withastro/starlight', + }, + sidebar: [ + { + label: 'Guides', + items: [ + // Each item here is one entry in the navigation menu. + { label: 'Example Guide', slug: 'guides/example' }, + ], + }, + { + label: 'Reference', + autogenerate: { directory: 'reference' }, + }, + ], + }), + ], +}); diff --git a/examples/markdoc/markdoc.config.mjs b/examples/markdoc/markdoc.config.mjs new file mode 100644 index 00000000..ecda158d --- /dev/null +++ b/examples/markdoc/markdoc.config.mjs @@ -0,0 +1,7 @@ +import { defineMarkdocConfig } from '@astrojs/markdoc/config'; +import starlightMarkdoc from '@astrojs/starlight-markdoc'; + +// https://docs.astro.build/en/guides/integrations-guide/markdoc/ +export default defineMarkdocConfig({ + extends: [starlightMarkdoc()], +}); diff --git a/examples/markdoc/package.json b/examples/markdoc/package.json new file mode 100644 index 00000000..d87a8ac6 --- /dev/null +++ b/examples/markdoc/package.json @@ -0,0 +1,20 @@ +{ + "name": "@example/starlight-markdoc", + "type": "module", + "version": "0.0.1", + "private": true, + "scripts": { + "dev": "astro dev", + "start": "astro dev", + "build": "astro build", + "preview": "astro preview", + "astro": "astro" + }, + "dependencies": { + "@astrojs/markdoc": "^0.11.4", + "@astrojs/starlight": "^0.26.1", + "@astrojs/starlight-markdoc": "^0.0.1", + "astro": "^4.15.3", + "sharp": "^0.32.5" + } +} diff --git a/examples/markdoc/public/favicon.svg b/examples/markdoc/public/favicon.svg new file mode 100644 index 00000000..cba5ac14 --- /dev/null +++ b/examples/markdoc/public/favicon.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/examples/markdoc/src/assets/houston.webp b/examples/markdoc/src/assets/houston.webp new file mode 100644 index 00000000..930c1649 Binary files /dev/null and b/examples/markdoc/src/assets/houston.webp differ diff --git a/examples/markdoc/src/content/config.ts b/examples/markdoc/src/content/config.ts new file mode 100644 index 00000000..45f60b01 --- /dev/null +++ b/examples/markdoc/src/content/config.ts @@ -0,0 +1,6 @@ +import { defineCollection } from 'astro:content'; +import { docsSchema } from '@astrojs/starlight/schema'; + +export const collections = { + docs: defineCollection({ schema: docsSchema() }), +}; diff --git a/examples/markdoc/src/content/docs/guides/example.mdoc b/examples/markdoc/src/content/docs/guides/example.mdoc new file mode 100644 index 00000000..ebd0f3bc --- /dev/null +++ b/examples/markdoc/src/content/docs/guides/example.mdoc @@ -0,0 +1,11 @@ +--- +title: Example Guide +description: A guide in my new Starlight docs site. +--- + +Guides lead a user through a specific task they want to accomplish, often with a sequence of steps. +Writing a good guide requires thinking about what your users are trying to do. + +## Further reading + +- Read [about how-to guides](https://diataxis.fr/how-to-guides/) in the Diátaxis framework diff --git a/examples/markdoc/src/content/docs/index.mdoc b/examples/markdoc/src/content/docs/index.mdoc new file mode 100644 index 00000000..814dc120 --- /dev/null +++ b/examples/markdoc/src/content/docs/index.mdoc @@ -0,0 +1,35 @@ +--- +title: Welcome to Starlight +description: Get started building your docs site with Starlight. +template: splash +hero: + title: Welcome to Starlight with Markdoc + tagline: Congrats on setting up a new Starlight project! + image: + file: ../../assets/houston.webp + actions: + - text: Example Guide + link: /guides/example/ + icon: right-arrow + - text: Read the Starlight docs + link: https://starlight.astro.build + icon: external + variant: minimal +--- + +## Next steps + +{% cardgrid stagger=true %} +{% card title="Update content" icon="pencil" %} +Edit `src/content/docs/index.mdoc` to see this page change. +{% /card %} +{% card title="Add new content" icon="add-document" %} +Add Markdoc files to `src/content/docs` to create new pages. +{% /card %} +{% card title="Configure your site" icon="setting" %} +Edit your `sidebar` and other config in `astro.config.mjs`. +{% /card %} +{% card title="Read the docs" icon="open-book" %} +Learn more in [the Starlight Docs](https://starlight.astro.build/). +{% /card %} +{% /cardgrid %} diff --git a/examples/markdoc/src/content/docs/reference/example.mdoc b/examples/markdoc/src/content/docs/reference/example.mdoc new file mode 100644 index 00000000..0224f096 --- /dev/null +++ b/examples/markdoc/src/content/docs/reference/example.mdoc @@ -0,0 +1,11 @@ +--- +title: Example Reference +description: A reference page in my new Starlight docs site. +--- + +Reference pages are ideal for outlining how things work in terse and clear terms. +Less concerned with telling a story or addressing a specific use case, they should give a comprehensive outline of what you're documenting. + +## Further reading + +- Read [about reference](https://diataxis.fr/reference/) in the Diátaxis framework diff --git a/examples/markdoc/src/env.d.ts b/examples/markdoc/src/env.d.ts new file mode 100644 index 00000000..e16c13c6 --- /dev/null +++ b/examples/markdoc/src/env.d.ts @@ -0,0 +1 @@ +/// diff --git a/examples/markdoc/tsconfig.json b/examples/markdoc/tsconfig.json new file mode 100644 index 00000000..bcbf8b50 --- /dev/null +++ b/examples/markdoc/tsconfig.json @@ -0,0 +1,3 @@ +{ + "extends": "astro/tsconfigs/strict" +} diff --git a/packages/markdoc/.npmignore b/packages/markdoc/.npmignore new file mode 100644 index 00000000..c8740c5e --- /dev/null +++ b/packages/markdoc/.npmignore @@ -0,0 +1 @@ +__tests__/ diff --git a/packages/markdoc/Code.astro b/packages/markdoc/Code.astro new file mode 100644 index 00000000..8c8a0609 --- /dev/null +++ b/packages/markdoc/Code.astro @@ -0,0 +1,16 @@ +--- +import { Code as Default } from '@astrojs/starlight/components'; + +interface Props { + code: string; + lang?: string; +} + +/** + * This component is a basic wrapper for the `` component from Starlight used for Markdoc + * fenced code blocks that ensures that we do not pass any child content to the `` component + * which is an usage not supported by Expressive Code and would throw an error. + */ +--- + + diff --git a/packages/markdoc/README.md b/packages/markdoc/README.md new file mode 100644 index 00000000..8141a004 --- /dev/null +++ b/packages/markdoc/README.md @@ -0,0 +1,18 @@ +# @astrojs/starlight-markdoc + +Markdoc preset for the [Starlight][starlight] documentation theme for [Astro][astro]. + +## Documentation + +See the [Starlight Markdoc docs][docs] for how to use this preset. + +## License + +MIT + +Copyright (c) 2024–present [Starlight contributors][contributors] + +[starlight]: https://starlight.astro.build/ +[astro]: https://astro.build/ +[docs]: https://starlight.astro.build/guides/authoring-content/#markdoc +[contributors]: https://github.com/withastro/starlight/graphs/contributors diff --git a/packages/markdoc/__tests__/markdoc.test-d.ts b/packages/markdoc/__tests__/markdoc.test-d.ts new file mode 100644 index 00000000..868f2c97 --- /dev/null +++ b/packages/markdoc/__tests__/markdoc.test-d.ts @@ -0,0 +1,127 @@ +import type { ComponentProps, HTMLAttributes } from 'astro/types'; +import { expectTypeOf, test } from 'vitest'; + +import { + Aside, + Badge, + Card, + CardGrid, + Code, + FileTree, + Icon, + LinkButton, + LinkCard, + Steps, + TabItem, + Tabs, +} from '@astrojs/starlight/components'; + +type UserComponents = keyof typeof import('@astrojs/starlight/components'); +type UserComponentProps any> = keyof RemoveIndexSignature< + ComponentProps +>; + +type MarkdocPreset = typeof import('../index.mjs').StarlightMarkdocPreset; +type MarkdocTags = keyof MarkdocPreset['tags']; +type MarkdocTagAttributes = keyof MarkdocPreset['tags'][T]['attributes']; + +test('defines a tag for each user components', () => { + expectTypeOf().toEqualTypeOf>(); +}); + +test('defines all `