# docs-sitekit

> Design system and scaffold for documentation microsites on GitHub Pages.

Install: `npx docs-sitekit init`. Repository: https://github.com/miguelcolmenares/docs-sitekit.

## Docs

- [Getting started](https://miguelcolmenares.com/docs-sitekit/docs/getting-started/): Create a documentation site for a repository in a few minutes.
- [Configuration reference](https://miguelcolmenares.com/docs-sitekit/docs/configuration/): Every key of sitekit.config.json, with its type, its default, the values it accepts and what it does.
- [Upgrading](https://miguelcolmenares.com/docs-sitekit/docs/upgrading/): Bring a site that sitekit init made up to the version of the kit you have installed, without losing what you changed.
- [Options by topic](https://miguelcolmenares.com/docs-sitekit/docs/options/): The same keys as the configuration reference, sorted by what you want to do, each with an example you can paste.
- [Options: identity and the home page](https://miguelcolmenares.com/docs-sitekit/docs/options-identity/): The keys that say what the site is, and what the home page shows first: site, hero, features and stats.
- [Options: navigation and collections](https://miguelcolmenares.com/docs-sitekit/docs/options-navigation/): The keys that decide what the reader can click: the header menu nav, the footer, the collections of pages, and the sources they are read from.
- [Options: theme and design](https://miguelcolmenares.com/docs-sitekit/docs/options-theme/): One key picks the theme a visitor sees first: theme.default. Everything else about the look is in design/tokens.json, not in the config.
- [Options: search and llms.txt](https://miguelcolmenares.com/docs-sitekit/docs/options-search-llms/): Two features of the site that you can turn on or off: the search dialog with search, and the map for language models with llms.
- [Options: content checks and publishing](https://miguelcolmenares.com/docs-sitekit/docs/options-checks/): The keys that decide what blocks a publish and what is kept out of the site: check, anonymize, vars and deploy.
- [Options: edit link and dates](https://miguelcolmenares.com/docs-sitekit/docs/options-edit-link/): Two lines at the foot of a page: a link to its source file on the repository host, with editLink, and the date of the last change, with lastUpdated.
- [Options: brand logos](https://miguelcolmenares.com/docs-sitekit/docs/options-brand-logos/): A brand logo is not a key of its own. It is a value of icon, in the cards of the features list.
- [Extending your site](https://miguelcolmenares.com/docs-sitekit/docs/extending/): A site made by sitekit init is yours, so you can add to it. These guides show six things people add, each one small and each one run as a test.
- [Add an interactive page](https://miguelcolmenares.com/docs-sitekit/docs/extend-tool-page/): Add a page that is not markdown, such as a configurator, a calculator or a playground, with its own script and styles.
- [Add a collection](https://miguelcolmenares.com/docs-sitekit/docs/extend-collection/): Add a set of pages with its own place in the menu, and decide the order and the groups of its sidebar.
- [Change a component, and keep the change](https://miguelcolmenares.com/docs-sitekit/docs/extend-component/): Add a component with add, change it, and see what add and sitekit upgrade do to the file you changed.
- [Change the tokens](https://miguelcolmenares.com/docs-sitekit/docs/extend-tokens/): Give the site a new accent in design/tokens.json, rebuild the CSS, and check the contrast of the new colors.
- [Add a logo and a layout of your own](https://miguelcolmenares.com/docs-sitekit/docs/extend-brand-and-layout/): Draw a brand logo the kit does not ship, and give one collection a page layout of your own.
- [Keep the build safe](https://miguelcolmenares.com/docs-sitekit/docs/extend-safe-build/): Know what sitekit check looks for before a site is published, and add a rule of your own to the closed config.
- [Components](https://miguelcolmenares.com/docs-sitekit/docs/components/): The design system is a set of React components, written in the shadcn style and rendered at build time. Only the copy button hydrates. The mobile menu is a native dialog and a few lines of script,…
- [Brand logos](https://miguelcolmenares.com/docs-sitekit/docs/brand-logos/): The icon of a feature in sitekit.config.json is a lucide name, and lucide has no brand logos. A logo is written as brand: instead:
- [Design tokens](https://miguelcolmenares.com/docs-sitekit/docs/design-tokens/): design/tokens.json is the single source of truth for colors, radius, fonts, layout and motion. npm run build:tokens turns it into CSS variables.
- [A detail page with a side card](https://miguelcolmenares.com/docs-sitekit/docs/detail-page/): A page with a card of metadata beside its text, written in the frontmatter.
- [Performance](https://miguelcolmenares.com/docs-sitekit/docs/performance/): A page of a generated site is drawn on a phone in about 2 seconds in Lighthouse's mobile test, and nothing on it moves when the web font arrives. This page says how the fonts and the menu are built…
- [Content](https://miguelcolmenares.com/docs-sitekit/docs/content/): How a markdown file becomes a page.
- [Callouts](https://miguelcolmenares.com/docs-sitekit/docs/callouts/): Highlight a note, a tip or a warning in a page, with plain markdown.
- [Code blocks](https://miguelcolmenares.com/docs-sitekit/docs/code-blocks/): A title, highlighted lines, added and removed lines, and a button that copies the code, all written in the fence.
- [Deploying](https://miguelcolmenares.com/docs-sitekit/docs/deploying/): The site is static, so GitHub Pages serves it directly.
- [Search](https://miguelcolmenares.com/docs-sitekit/docs/search/): Every site has a search dialog. A reader opens it with the search button in the header, with Ctrl K or Cmd K, or with the slash key when no field has the focus.
- [llms.txt](https://miguelcolmenares.com/docs-sitekit/docs/llms/): An optional map of the site for language models, written as Markdown.
- [Edit this page and the date of the last change](https://miguelcolmenares.com/docs-sitekit/docs/edit-link/): A link at the foot of each page to its source file, and the date the file last changed.

## Components

- [Button](https://miguelcolmenares.com/docs-sitekit/components/button/): Button and buttonVariants, from shadcn/ui, with the look of the kit.
- [ToneBadge](https://miguelcolmenares.com/docs-sitekit/components/tone-badge/): The only way to show a status color.
- [Icon](https://miguelcolmenares.com/docs-sitekit/components/icon/): A lucide icon by its kebab-case name, or a brand logo as brand:<slug>.
- [SectionHeader](https://miguelcolmenares.com/docs-sitekit/components/section-header/): Mono eyebrow, heading and lede.
- [Hero](https://miguelcolmenares.com/docs-sitekit/components/hero/): Badge, headline, lede, command and actions.
- [CtaBand](https://miguelcolmenares.com/docs-sitekit/components/cta-band/): Closing headline with a command and actions.
- [SiteFooter](https://miguelcolmenares.com/docs-sitekit/components/site-footer/): Brand, link columns and a legal bar.
- [ItemCard](https://miguelcolmenares.com/docs-sitekit/components/item-card/): ItemCard and CardGrid for catalogs.
- [FeatureGrid](https://miguelcolmenares.com/docs-sitekit/components/feature-grid/): Icon, eyebrow, title and text.
- [StatRow](https://miguelcolmenares.com/docs-sitekit/components/stat-row/): Two to five numbers, each with a label and a note.
- [FlowDiagram](https://miguelcolmenares.com/docs-sitekit/components/flow-diagram/): Steps in a row that stack on small screens.
- [Callout](https://miguelcolmenares.com/docs-sitekit/components/callout/): A note, a tip, an important point, a warning or a caution.
- [SideCard](https://miguelcolmenares.com/docs-sitekit/components/side-card/): A card of metadata, links and tags beside the text of a detail page, collapsed on a phone.
- [ReferenceTable](https://miguelcolmenares.com/docs-sitekit/components/reference-table/): A table for a reference: names in code, a type, a default, allowed values and a text, in a scrollable region.
- [CommandTable](https://miguelcolmenares.com/docs-sitekit/components/command-table/): A command and what it does.
- [CommandBox](https://miguelcolmenares.com/docs-sitekit/components/command-box/): A copyable shell command.
- [Breadcrumbs](https://miguelcolmenares.com/docs-sitekit/components/breadcrumbs/): Breadcrumb trail for a page.
- [CatalogFilter](https://miguelcolmenares.com/docs-sitekit/components/catalog-filter/): A text field and tag buttons that narrow the cards of an index page, with the state in the address.
- [PageInfo](https://miguelcolmenares.com/docs-sitekit/components/page-info/): The line at the foot of a page: an edit link and the date of the last change.

## Changelog

- [Changelog](https://miguelcolmenares.com/docs-sitekit/changelog/): All notable changes to this project are documented in this file.

## Optional

- [Basic site](https://miguelcolmenares.com/docs-sitekit/examples/basic/): The smallest useful configuration: a name, a description, a URL and a hero.