# Autodoc Generated pages document a whole package. This is the default way to show your API reference. `` covers a different case: a page you write by hand that needs one class or function in the middle of the text, rendered exactly as the generated pages render it. It is the component form of mkdocstrings' `::: demopkg.generate_report` directive. [Migrating from mkdocstrings](/starlight-pydocs/guides/migration/) maps the rest of the directive's options onto props. ## Put a block in a page The page must be `.mdx`. A `.md` page cannot The helper that writes one for you: {/* Name the object where you want it rendered. */} Pass `fmt` when you want something other than Markdown. ``` `name` takes either the path an object is documented at, or the canonical path Griffe found the definition at. Both paths reach the same object. `package` says which configured entry to read it from. That same line sits on this page. Everything in the box below is what it renders. The heading, the signature, the parameter table and the return value all come from the function's own docstring. None of it comes from anything written here. :::tip[Rendered output] ::: ## Props | Prop | Type | Default | What it does | | -------------- | ----------------- | -------------------- | ----------------------------------------------- | | `name` | `string` | required | Dotted path of the object to document | | `package` | `string` | inferred from `name` | Which configured entry to document it from | | `headingLevel` | `number` | `2` | Heading depth for the object; members go deeper | | `labels` | `StringOverrides` | site translations | UI label overrides for this block alone | A class or function brings its members with it. Naming a module renders the whole module, the same way a generated module page does, including the member summary and submodule list. A module has no heading of its own here, so for a module, `headingLevel` sets the depth of its members. `labels` lets a page in a plain Astro site translate a block. It also lets a Starlight site change one string in one place. See [Internationalisation](/starlight-pydocs/guides/i18n/#without-starlight). ## Choosing the package The dotted name usually says which package an object belongs to, so `package` is optional. It becomes required when one package is documented at more than one base, because then the import name identifies two entries. Give it the base of the one you mean: ```mdx "package" ``` This site documents `demopkg` twice (the current source and the archived 1.x dump), which is why every block on this page names its base. Leave `package` off and the build stops with the candidates listed: ```text wrap starlight-pydocs: is ambiguous: 'demopkg' is documented at 2 bases. Set the package prop to one of these bases: 'api/demopkg', '1x/api/demopkg'. ``` `package` also accepts a plain import name where that name is unambiguous. A base always wins over a name when both would match. A name that resolves to a package, but not to an object in it, fails the same way. This is usually a typo, or a `members`/`filters` setting that excludes the object from that entry: ```text wrap starlight-pydocs: is not documented at '/api/demopkg'. Check the spelling, or the members/filters options that may be excluding it. ``` ## Heading levels `headingLevel` sets the depth of the object's own heading. Its members go one level deeper. Use it to place a block under a section of your own, without breaking the document outline: ```mdx title="src/content/docs/reporting.mdx" {5} ## Building a report The helper that wires one together for you: ``` Below is the same function as the block further up this page, rendered again at `headingLevel={5}`. Its heading is an `h5` instead of an `h2`, and its parameters sit at `h6`. Everything else about the two blocks is identical. :::tip[Rendered output] ::: ## Anchors and the table of contents Every heading a block emits has the dotted object path as its `id`. This is the same anchor scheme the generated pages and mkdocstrings use, so `#demopkg.generate_report` above is a working permalink. Those headings do not reach Starlight's **On this page** panel. The panel is built from the Markdown headings of the page itself, and a component's output is not one of them. The panel beside this guide proves it: it lists `Heading levels`, not `demopkg.generate_report`. Add your own `##` heading above a block when you want a table of contents entry for it. The generated pages stay an object's canonical home either way. [Cross-references](/starlight-pydocs/guides/cross-references/) and the published `objects.inv` are built from the page plan. So `[Report][demopkg.report.Report]` in a docstring resolves to the generated `demopkg.report` page, never to a hand-placed copy of the same object. ## Symbol search `` searches one package's API surface by name. It runs client-side, using the `symbols.json` index the plugin publishes. It is already on the generated package pages; this is the same component placed by hand. It takes the same `package` prop, a base or an unambiguous import name, and defaults to the first configured entry. [Search](/starlight-pydocs/guides/search/) covers the index, the ranking and the rest of its props. The box below searches `demopkg`. Type `generate`: [Component overrides](/starlight-pydocs/guides/component-overrides/) [Search](/starlight-pydocs/guides/search/) [Vanilla Astro](/starlight-pydocs/guides/vanilla-astro/)