Anti-patterns
Don't hand-edit generated files
These are auto-generated by magicms and will be overwritten on next block install, schema change, or scaffold upgrade:
src/components/BlockRenderer.astrosrc/components/SectionRenderer.astrosrc/content.config.generated.tssrc/lib/jsonLdRegistry.tssrc/lib/collectionJsonLdRegistry.tssrc/styles/fonts.csssrc/styles/inline-text-safelist.css
Edit the underlying blocks or schemas instead. Manual edits to these files will be overwritten.
Naming
- Block names: PascalCase —
Hero,TeamGrid.herowill not matchHero.astroon case-sensitive file systems. - Field keys: camelCase —
heroTitle,backgroundImage. - Collection names: camelCase —
team,blogPost. - Global names: camelCase —
header,footer. - Slugs: kebab-case —
about-us,team-grid.
List vs. translation
Pick one pattern per list field. Don't mark both the list and its sub-fields as translatable. The list flag wins, and the sub-field flags become dead code.
MagicCms ↔ filesystem
- Case sensitivity: filenames must match the schema
_typeexactly (PascalCase). - Slug collisions: two pages can't share a slug in the same language.
- Drag-and-drop: ordering is stored in
.structure.json(nodes[]order), not in the filesystem. - Restoring deleted files: if you delete a
.structure.jsonoutside the CMS, the page is gone. Restoring requires agit revert— the CMS cannot recreate it.