Skip to content
Documentation

Project structure

What teakit-astro create writes, where the boundary with the framework falls, and how the tree becomes the site.

A scaffolded Teakit project is an ordinary Astro project. Everything you will edit is a real file in your repository; all three packages stay dependencies and are never copied in.

npx --package @teakit/astro teakit-astro create my-docs

What lands in your repository

text
my-docs
├── .gitignore
├── .npmrc
├── astro.config.mjs
├── index.css
├── package.json
├── tsconfig.json
└── src
    ├── i18n.ts
    ├── content.config.ts
    ├── content
    │   └── docs
    │       └── en
    │           ├── index.mdx
    │           └── brewing.md
    ├── components
    │   ├── ComponentExample.astro
    │   ├── LanguageSwitcher.astro
    │   └── LibrarySwitcher.astro
    ├── helpers
    │   ├── docs.ts
    │   ├── libraries.ts
    │   ├── locales.ts
    │   └── sidebar.ts
    ├── layouts
    │   └── DocsLayout.astro
    └── pages
        └── [...slug].astro
Path What it is
.npmrc Maps the @teakit scope to the Yiplex hub and reads the token from HUB_TOKEN
index.css The TeaCSS entry — presets, @source globs, @teacss;. This file is the configuration; there is no teacss.config.*
astro.config.mjs teacss() and teakit() with the locale options, plus redirects from / to /en/docs, markdown.shikiConfig, prefetch, and vite.resolve.noExternal
src/i18n.ts The default locale and the locale list; the scaffold starts with English only
src/content.config.ts The docs collection, from astro’s contentCollection()
src/content/docs/en/ Your English pages. The tree here is the site
src/helpers/ The glue: collection entries in, navigation, sidebar, libraries and interface strings out
src/components/ The library and language switchers, and a code example with a copy button
src/layouts/DocsLayout.astro The page chrome — shell, sidebar, breadcrumb, table of contents and appearance switch
src/pages/[...slug].astro One route for every page, and the landing page too — there is no separate index.astro

Two of the files are seed content. One .md and one .mdx on purpose: the pair proves both parse paths the moment the dev server starts. Add a locale to src/i18n.ts and a matching folder under src/content/docs/ to translate.

The tree is the structure

The directory layouts under src/content/docs/ and src/content/package-docs/ define the URL structure and the sidebar. The path is the structure — guides/installing nests under guides whether or not guides is a page in its own right.

text
src/content
├── docs
│   ├── index.mdx            → /docs
│   └── project-structure.mdx → /docs/project-structure
└── package-docs
    ├── astra.mdx            → /packages/astra
    ├── astra
    │   └── accordion.mdx    → /packages/astra/accordion
    ├── teacss.mdx           → /packages/teacss
    └── teacss
        ├── concepts.mdx    → /packages/teacss/concepts
        ├── standard.mdx    → /packages/teacss/standard
        ├── official.mdx    → /packages/teacss/official
        └── icons.mdx       → /packages/teacss/icons

A directory with no entry of its own becomes a heading in the sidebar: its slug and href are null, it is not navigable, and it takes its label from the path segment, title-cased. An entry alongside a same-named directory makes that group navigable, as with TeaCSS Concepts, Standard, Official, and Icons. Package pages define the navigable roots; folders below them group their references.

Move a file and its route and its sidebar entry move with it. Frontmatter handles the fine grain — sidebar.order, sidebar.badge, draft — but the shape of the site comes from the filesystem. There is no second navigation config to keep in sync, so the site cannot drift from its own contents.

What is yours and what is not

The three packages divide by what they produce:

Package Ships Knows about
@teakit/astra elements — Button, Dialog, Prose behaviour and accessibility
@teakit/aster blocks — Shell01, Sidenav01, Pricing01 arrangement
@teakit/astro data helpers, the Astro integration, the CLI your content

The direction is one-way: aster composes astra, your page composes both, and astro imports neither. astro computes, astra draws, aster arranges, the page glues — which is why PackageManagers takes commands already translated rather than importing astro’s translatePackageCommand itself.

Nothing is vendored. There is no upstream theme to override and no copy in your repository to diff against, so upgrading the chrome is npm update.

What the integration adds

teakit() in your Astro config injects three routes you never write:

Route Contents
/llms.txt The sidebar flattened to links and descriptions
/llms-full.txt Every page body as markdown, slug-ordered
/[...slug].md One page body as markdown

They are wired together on purpose: an agent reads /llms.txt, follows a link, and gets markdown rather than HTML it has to strip. Try /llms.txt or the markdown twin of this page, /docs/project-structure.md.

To take one over, create the file — src/pages/llms.txt.ts and that route is yours, no option required.

What is not in the tree

.astro/ is generated: content-collection types and the resolved config. It is gitignored, and nothing in it is yours to edit.

There is no config file of astro’s own. Everything it needs is an option on the teakit() call, and nothing else in the project reads one — including site, which stays on Astro’s defineConfig because the sitemap, the canonical URL, and Astro.site all read it from there.