Beauty Affairs HK theme documentation

The repository is a Shopify theme with a TypeScript application on top of it. Conversion Kings writes the code in src/, and Vite compiles it. Everything outside src/ follows the standard Shopify theme layout. The theme started as Prestige 10.0.2 and has been customised for years since.

Where to start

You run the store. You want to change a price threshold, some wording, a gift, or a popup. Start at Operations. Most of what you need is in Shopify admin, either under Online Store > Themes > Customize or in a product's metafields. You do not need to read the developer pages.

You are changing the code. Start at the Developer guide. Read Local development first, then the Codebase map. When you need to find where something lives, use Entrypoints. It maps every compiled bundle to the Liquid file that loads it.

Something is broken right now. Go to Runbooks.

You want to know why it works this way. Go to Architecture.

You need an exact field name, setting, or metafield. Go to Reference.

Before you change anything

The repository holds 133 template files and 134 sections, and many of them belong to apps the store no longer uses. Before you edit a file because its name looks right, check Legacy and unused code.

Two build outputs are committed to git, snippets/vite-tag.liquid and src/entrypoints/theme.styles.css. A hand edit to either one lasts until the next build overwrites it. Build pipeline explains what generates them.

The store has one live theme and several unpublished themes. npm run push runs shopify theme push, and shopify.theme.toml does not name a theme, so Shopify CLI asks you to pick the theme to overwrite. The live theme is in that list. Run npm run list first and pick by theme ID.

System summary

The mini-cart, the Medispa booking calendar and the popup manager hold most of the custom logic. Each one has an architecture page and an operations page.

Keeping these docs accurate

When you change how something works, change the page that describes it in the same pull request. The pages that go out of date fastest are Entrypoints, Theme settings and Legacy and unused code.

This site is a Fumapress app in doc-site/. Pages live in doc-site/content/, and each folder's meta.json sets the sidebar order. Three scripts keep the mechanical parts accurate. Run them from the repository root.

python3 doc-site/validate.py                        # frontmatter, links, sidebar, cited paths, prose
python3 doc-site/scripts/build-entrypoint-table.py  # rebuild the entrypoint tables
python3 doc-site/diagrams/generate.py               # rebuild the SVGs and Excalidraw sources

validate.py checks that every page has a frontmatter title, every relative link resolves, every meta.json lists the pages in its folder, every repository path cited in backticks exists, and the prose avoids the patterns the project's unslop skill lists. It exits non-zero on failure, so it works in a pre-commit hook or CI.

The two generators overwrite their output. Edit doc-site/diagrams/generate.py rather than the SVG or Excalidraw files, and edit the NOTES map in doc-site/scripts/build-entrypoint-table.py rather than the generated table.

Link between pages with a relative file path that starts with ./ or ../. From this page, for example, the glossary is ./reference/glossary.md. Fumadocs only rewrites links in that form, and npm run build in doc-site/ fails on any link that does not resolve.