Find what to change
Go from something you see on your site to the place that changes it, including the parts that are not in your repository.
On this page
For developers. You see something on your site and want to change it, but you cannot find the file. This page takes you from what you see to the place that changes it. You do not need to know Astro to use it.
Why you cannot find the file
A generated site is small on purpose. The engine is in the kit, the package @mdlake/site-kit, which is installed in node_modules. A new site’s src/ folder holds configuration and design tokens. It has no home page, no header and no footer, so searching your repository for them finds nothing.
Nothing is missing. Everything on a page comes from one of three places:
| Where | What it holds | How you change it |
|---|---|---|
| The lake | All the words and images | Edit in the CMS and publish |
plan.md and design.md | Which pages exist, what they show, colours and fonts | Edit the file and run a command |
| The kit | How things are drawn: the header, the footer, the modules | Write your own file and register it. The kit stays as it is. |
From what you see to where to change it
| You want to change | It comes from | Do this |
|---|---|---|
| Text on a page | A document in the lake | Edit it in the CMS and publish |
| The browser title or search description of a page | The document’s title and summary | Edit them in the CMS and publish |
| The order of the docs sidebar | Folder and document order in the lake | Drag them into place in the CMS |
| The logo | An asset in the lake, in slots in plan.md | Change logo, then run plan-to-config |
| The share image | An asset in the lake, in slots in plan.md | Change ogImage, then run plan-to-config |
| The site name | name in the yaml site block of plan.md | Change it, then run plan-to-config |
| Colours, fonts, corner radius | design.md | Edit it, then run regenerate |
| Which pages exist, the links in the header | plan.md | Edit it, then run plan-to-config |
| Which modules a page has, and their order | plan.md | Edit it, then run plan-to-config |
| The favicon | public/favicon.svg | Replace the file |
| An old address that should still work | redirects.json | Add "/old/": "/new/" |
| The header or the footer | The kit’s layout | Write your own layout and register it in site.config.ts |
| The home page, or how one kind of module looks | A kit module | Write your own module and register it in site.config.ts |
| A page that fits no module, or the 404 page | A route | Add a file to src/pages/. Your file wins over the kit’s route. |
The commands are these. Run them in the site folder.
node "<plugin>\scripts\plan-to-config.mjs" .
node "<plugin>\scripts\apply-design.mjs" .plan-to-config rewrites lake.config.ts and src/pages.config.ts, so do not edit those two by hand. apply-design writes the tokens into src/styles/global.css. The regenerate skill runs it for you and checks the result.
Changes in the lake reach the site with its next build. A site in live mode reads the newest content when it builds. A site in snapshot mode moves with the refresh-content skill.
Which module draws a part of a page
Open src/pages.config.ts and find the route. Its modules are listed from the top of the page to the bottom.
home: {
path: '/',
modules: [
{ module: 'hero', from: { document: 'home' } },
{ module: 'featureGrid', from: { collection: 'services' } },
{ module: 'cta', from: { document: 'contact' } },
],
},Then read the kit’s file to see how that part is drawn. All paths below are in node_modules/@mdlake/site-kit/dist/.
| Part of the page | Name in site.config.ts | Kit file |
|---|---|---|
| Header, footer and the frame around each page | layout | layouts/Layout.astro |
| The large opening block | hero | components/modules/Hero.astro |
| A grid of cards | featureGrid | components/modules/FeatureGrid.astro |
| Numbered steps | steps | components/modules/Steps.astro |
| A quote | testimonial | components/modules/Testimonial.astro |
| Key figures | stats | components/modules/Stats.astro |
| Questions and answers | faq | components/modules/FAQ.astro |
| A call to action | cta | components/modules/CTA.astro |
| A document as an article | richText | components/modules/RichText.astro |
| The top of a customer story | caseHeader | components/modules/CaseHeader.astro |
| The docs home and each docs page | docsPage | components/modules/DocsPage.astro |
| A form | form | components/modules/Form.astro |
| The block at the end of a detail page | endOfPage | components/modules/EndOfPage.astro |
The header and the footer have no file of their own. They are written directly in Layout.astro.
Smaller shared parts are in components/, such as MobileNav.tsx, DocsSidebar.tsx, DocsSearch.tsx and LakeImage.astro. You replace those with parts in site.config.ts.
Warning
Read these files, but do not edit them. The next install puts them back, and your change is gone. Copy what you need into your own file instead.
Your own files
Your own files are never touched by a skill, a refresh or an upgrade. npx mdlake ownership shows who owns what.
| Folder | What goes there | Also needed |
|---|---|---|
src/pages/ | A whole page at its own address | Nothing. The file name is the address. |
src/layouts/ | Your layout | layout in site.config.ts |
src/components/ | Your modules and components | modules in site.config.ts for a module |
Create site.config.ts when you need it. Everything you do not name in it still comes from the kit.
What can go wrong
| Symptom | Cause and fix |
|---|---|
| A search of the repository finds nothing | The part is in the kit or the lake. Use the table above. |
A change in node_modules disappeared | Installing restores the kit. Register your own file instead. |
plan-to-config says a file was edited by hand | Someone changed a generated file. Read the summary, then keep the edit by adopting the file, or run the script again with --overwrite. See Ownership zones. |
| Text is still the old text after publishing | The site has not been built since. Run a new build, or the refresh-content skill in snapshot mode. |
| Your new file has no effect | It is not registered in site.config.ts, or astro dev was not restarted after you registered it. |
What’s next
- Change the header, footer and home page for a worked example, with the Astro you need to read it.
- Custom components for the rules of an override.
- Ownership zones for who owns each file.