Project Structure and Conventions (Kecare)

Regardless of the technology stack or framework, be it Vue, React, Svelte, or traditional server-side rendering frameworks, any existing project, or a new project you create using your preferred technology stack, can be transformed into a blog simply by creating a .kecare directory. It will generate blog pages for you based on the rules you define.

1. Directory Structure

Kecare-theme/                       # 主题根目录（themeDir）
├─ .kecare/                          # Kecare 约定目录（）
│  ├─ articles/                      # 文章源文件（Markdown）
│  │  ├─ hello-kecare.md
│  │  └─ ...
│  └─ menus/                         # 菜单源文件（TypeScript）
│  │  ├─ kecare-docs.menu.source.ts
│  │  └─ ...
│  └─ en-US.trans.ts                      # 英文翻译配置文件
│
...

.kecare/ is the most crucial part of the Kecare system: writers' content goes here, menus go here, and theme authors by default also fetch content from here, ne~

2. .kecare/ Directory Conventions

2.1 .kecare/articles/：Article Directory

Location fixed: theme directory/.kecare/articles/
File type: Currently only supports *.md
Recommended naming: Use stable, readable English filenames (e.g., getting-started.md), avoid frequent renaming

Why is it not recommended to randomly change file names?

Because in common implementations of Kecare, the id of an article is often derived from the hash of the file name, thereby forming a stable link.

The file name changed → id may change → old links may become invalid, meow~

Location fixed: theme directory/.kecare/menus/
File naming fixed: *.menu.source.ts
File content convention: export navItems: NavItem[]

3. How the Theme Layer Consumes Data (For Theme Authors)

Kecare's generator typically parses articles into structured object arrays (e.g., articles: Article[])

Project Structure Conventions