{"$schema":"https://doc-kit.nodejs.org/schemas/api-doc/1.0.1.json","id":"generators-jsx-ast","path":"/generators/jsx-ast","type":"module","module":"generators-jsx-ast","title":"Page JSX","introducedIn":null,"sourceLink":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"The `jsx-ast` stage turns each page's API entries into the JSX that the\n[website](https://doc-kit.nodejs.org/generators/html) renders. It runs whenever\nyou build the site; configure it to change how your Markdown becomes pages.\n\n**Stage:** `jsx-ast` · **Package:** [`@doc-kit/generator-react`](https://doc-kit.nodejs.org/packages/react) · **Reads:** [API entries](https://doc-kit.nodejs.org/generators/metadata) · **Writes:** no files","summary":"The `jsx-ast` stage turns each page's API entries into the JSX that the website renders. It runs whenever you build the site; configure it to change how your Markdown becomes pages.","examples":[],"children":[{"kind":"section","id":"usage","name":"Usage","title":"Usage","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"You don't request `jsx-ast` yourself: building the website runs it, since\n`html` depends on it.\n\n```bash\nnpx doc-kit generate -t html -i \"docs/**/*.md\" -o out\n```\n\n```text\nast → metadata → jsx-ast → html\n```\n\nWith [section pages](https://doc-kit.nodejs.org/generators/section-pages),\n`section-pages` runs between `metadata` and `jsx-ast`, so the section pages are\nbuilt here like any other page.","summary":"You don't request `jsx-ast` yourself: building the website runs it, since `html` depends on it.","examples":[{"language":"bash","displayName":null,"code":"npx doc-kit generate -t html -i \"docs/**/*.md\" -o out"},{"language":"text","displayName":null,"code":"ast → metadata → jsx-ast → html"}],"children":[]},{"kind":"section","id":"configuring","name":"Configuring","title":"Configuring","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"Options go in the `jsx-ast` section of the\n[configuration file](https://doc-kit.nodejs.org/configuration):\n\n```mjs displayName=\"doc-kit.config.mjs\"\nexport default {\n  global: {\n    // Source links are built from it\n    repository: 'my-org/kittens',\n  },\n\n  'jsx-ast': {\n    // Link to the release branch instead of main\n    ref: 'v2.x',\n    showReadingTime: true,\n  },\n};\n```\n\n* `ref` {string} The Git ref of the \"Source Code\" link that an entry with a\n  `source_link` gets under its heading, which points at\n  `https://github.com/<repository>/blob/<ref>/<source_link>`. The default wins\n  over `global.ref`, so `--git-ref` doesn't change it. **Default:** `'main'`.\n* `generateNotFoundPage` {boolean} Whether to build the `404` page.\n  **Default:** `true`.\n* `showReadingTime` {boolean} Whether to estimate each page's reading time,\n  such as `1 min read`, which the site shows in the page's meta bar.\n  **Default:** `false`.\n* `markdown` {Object} Your own [unified](https://unifiedjs.com/) plugins for\n  the pages, added after the ones in `global.markdown`. See\n  [The Markdown pipeline](#the-markdown-pipeline).\n  * `remarkPlugins` {Array} Run on each page's Markdown syntax tree, before\n    GitHub alerts are built. Global remark plugins don't run here: they\n    already ran when `ast` parsed the files.\n  * `rehypePlugins` {Array} Run on the HTML syntax tree, before code is\n    highlighted.\n  * `recmaPlugins` {Array} Run on the JavaScript syntax tree, before the JSX\n    is printed.\n\nSet `repository` in `global` whenever your pages use `source_link`.","summary":"Options go in the `jsx-ast` section of the configuration file:","examples":[{"language":"mjs","displayName":"doc-kit.config.mjs","code":"export default {\n  global: {\n    // Source links are built from it\n    repository: 'my-org/kittens',\n  },\n\n  'jsx-ast': {\n    // Link to the release branch instead of main\n    ref: 'v2.x',\n    showReadingTime: true,\n  },\n};"}],"children":[]},{"kind":"section","id":"what-gets-a-page","name":"What gets a page","title":"What gets a page","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"`jsx-ast` builds one page per document, holding all of that document's\nentries:\n\n* Every document with a `#` heading gets a page, and so does a document with\n  no headings at all. A document whose headings all start at `##` or deeper\n  gets no page, so give each document a title.\n* With `generateNotFoundPage`, it adds a \"Page Not Found\" page that links back\n  to `index.html`. `html` writes it as `404.html`, and your layout can tell it\n  apart by its `api`, `'404'`.\n* `all.html` isn't built here. `html` assembles it from the module pages'\n  content (see its `generateAllPage` option), so no module is built twice.\n\nPages are ordered with `index`, `synopsis` and `documentation` first, then by\ntitle. The sidebar (unless you configure `navigation.sidebar`), `all.html` and\n`<DocumentationIndex />` all follow that order.","summary":"`jsx-ast` builds one page per document, holding all of that document's entries:","examples":[],"children":[]},{"kind":"section","id":"the-index-page","name":"The index page","title":"The index page","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"An `index.md` or `index.mdx` at the top level of your input becomes\n`index.html`, the site's home page. It's rendered like any other page, and\n`all.html` leaves it out.\n\nTo list every page on it, write it in MDX and use the built-in\n`<DocumentationIndex />` component, which needs no registering:\n\n```mdx displayName=\"docs/index.mdx\"\n# Kittens\n\nAn API for feeding, petting and scheduling naps.\n\n<DocumentationIndex />\n```\n\n`<DocumentationIndex />` links to every module page other than the index\n(section pages and the `404` page aren't listed). Each entry shows the page's\ntitle, its stability badge when the page has a page-level stability index, and\nits description: the page's `llm_description`, or else its first paragraph.\n\nComponents only work in MDX. In a `.md` page, `<DocumentationIndex />` stays an\nunknown HTML tag and renders nothing.","summary":"An `index.md` or `index.mdx` at the top level of your input becomes `index.html`, the site's home page. It's rendered like any other page, and `all.html` leaves it out.","examples":[{"language":"mdx","displayName":"docs/index.mdx","code":"# Kittens\n\nAn API for feeding, petting and scheduling naps.\n\n<DocumentationIndex />"}],"children":[]},{"kind":"section","id":"what-the-markdown-becomes","name":"What the Markdown becomes","title":"What the Markdown becomes","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"Most of a page becomes plain HTML, but `jsx-ast` turns some parts into the\nwebsite's components:\n\n| In the Markdown                                                | On the page                                                                                                                                            |\n| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| Headings                                                       | An `id` from the heading's slug and a link to itself, a `DataTag` badge for the entry's kind (class, method, event and so on), and its change history. |\n| Method, constructor and class method headings                  | A highlighted signature built from the heading and its typed list, such as `kittens.pet(name): boolean`. Classes get one when they extend another.     |\n| Typed lists                                                    | A table of attributes (`FunctionSignature`). In MDX pages, lists stay lists.                                                                           |\n| Type annotations, such as `{string}`                           | Highlighted code that links to the type's documentation.                                                                                               |\n| Stability blockquotes                                          | An `AlertBox` colored by level: 0 danger, 1 warning, 2 success, 3 info.                                                                                |\n| GitHub alerts, such as `> [!NOTE]`                             | An `AlertBox` titled Note, Tip, Important, Warning or Caution.                                                                                         |\n| Fenced code                                                    | Shiki-highlighted code in a `CodeBox`, with its language and a copy button (left out for one-line blocks). Blocks under 5 lines have no line numbers.  |\n| Adjacent fenced code blocks                                    | `CodeTabs`, one tab per block, labelled by its `displayName` or else its language. `active=\"true\"` picks the tab shown first.                          |\n| Other blockquotes                                              | A `Blockquote`.                                                                                                                                        |\n| Tables                                                         | Wrapped in a scrolling container, with each cell labelled by its column header for narrow screens.                                                     |\n| Footnotes                                                      | Moved to the end of the page's content.                                                                                                                |\n| The `Type:` line under each `###` heading of `deprecations.md` | An `AlertBox`: info for Documentation or Compilation, warning for Runtime or Application, danger otherwise.                                            |\n\n[Writing documentation](https://doc-kit.nodejs.org/writing-docs) covers how to\nauthor each of these.","summary":"Most of a page becomes plain HTML, but `jsx-ast` turns some parts into the website's components:","examples":[],"children":[]},{"kind":"section","id":"the-markdown-pipeline","name":"The Markdown pipeline","title":"The Markdown pipeline","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"Each page's tree runs through one [unified](https://unifiedjs.com/) processor,\nin three steps. Your plugins slot into each one:\n\n1. **remark**, on the Markdown syntax tree: the remark plugins in\n   `jsx-ast.markdown`, then GitHub alerts. Your plugins run first, so they can\n   produce alerts too.\n2. **rehype**, on the HTML syntax tree, in this order:\n   1. Conversion with `remark-rehype` (raw HTML kept, JSX passed through,\n      types highlighted) and `rehype-raw`.\n   2. The rehype plugins in `global.markdown`, then those in\n      `jsx-ast.markdown`.\n   3. Shiki, which highlights code and groups adjacent blocks into tabs.\n   4. The `CodeBox`, `Blockquote`, table and footnote changes.\n3. **recma**, on the JavaScript syntax tree: `rehype-recma` and `recma-jsx`,\n   then the recma plugins in `global.markdown` and `jsx-ast.markdown`, then\n   `recma-stringify`.\n\nA plugin that adds Markdown syntax, such as `remark-math`, belongs in\n`global.markdown.remarkPlugins`: the files are parsed in `ast`, which runs the\nglobal remark plugins, and `jsx-ast` doesn't parse them again.\n\n```mjs displayName=\"doc-kit.config.mjs\"\nexport default {\n  global: {\n    markdown: {\n      // Parses math wherever the files are parsed\n      remarkPlugins: ['remark-math'],\n    },\n  },\n\n  'jsx-ast': {\n    markdown: {\n      // Renders it on the site's pages\n      rehypePlugins: ['rehype-katex'],\n    },\n  },\n};\n```\n\n[Markdown plugins](https://doc-kit.nodejs.org/configuration#markdown-plugins)\ncovers how to list a plugin, with or without options, and how its specifier\nis resolved.\n\nListing a plugin that `jsx-ast` already has, such as\n`@doc-kit/core/plugins/shiki/rehype.mjs`, configures it instead of adding it\ntwice. That's how you change the code themes or add languages; see\n[Code highlighting](https://doc-kit.nodejs.org/configuration#code-highlighting).\nYour plugins don't run on the small fragments `jsx-ast` renders on their own:\nthe types and descriptions in typed lists, and change history notes.","summary":"Each page's tree runs through one unified processor, in three steps. Your plugins slot into each one:","examples":[{"language":"mjs","displayName":"doc-kit.config.mjs","code":"export default {\n  global: {\n    markdown: {\n      // Parses math wherever the files are parsed\n      remarkPlugins: ['remark-math'],\n    },\n  },\n\n  'jsx-ast': {\n    markdown: {\n      // Renders it on the site's pages\n      rehypePlugins: ['rehype-katex'],\n    },\n  },\n};"}],"children":[]},{"kind":"section","id":"what-it-produces","name":"What it produces","title":"What it produces","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"A [custom generator](https://doc-kit.nodejs.org/creating-generators) with\n`dependsOn: '@doc-kit/generator-react/jsx-ast'` receives an array with one\nobject per page, in the order the worker threads finished them rather than page\norder:\n\n* `data` {Object} The page's head entry from `metadata`, with its `api`,\n  `path`, heading and metadata.\n* `headings` {Array} The table of contents: the page's headings down to `###`,\n  with an overloaded function listed once.\n  * `depth` {number} The heading level.\n  * `value` {string} The label, such as `fs.readFile` for a method.\n  * `slug` {string} The heading's `id`.\n  * `stability` {number} The entry's stability index, `2` when it has none.\n  * `data` {Object} The heading's `id` and the entry's `type`.\n* `readingTime` {string | undefined} The estimated reading time, when\n  `showReadingTime` is on.\n* `content` {string} The page's content as JSX code: one fragment, without a\n  layout. It uses the components above by name, without importing them.\n\n`html` provides those components, wraps each page in its `#theme/Layout`, and\nbuilds `all.html` from the module pages' `content`.","summary":"A custom generator with `dependsOn: '@doc-kit/generator-react/jsx-ast'` receives an array with one object per page, in the order the worker threads finished them rather than page order:","examples":[],"children":[]}]}