From 7671633220712149953e3dc1aa56c3cf376f2ddc Mon Sep 17 00:00:00 2001 From: Florian <45694132+flo-bit@users.noreply.github.com> Date: Fri, 24 Apr 2026 13:05:51 +0200 Subject: [PATCH] update docs --- README.md | 9 +++++++- docs/01-configuration.md | 26 ++++++++++++++++++++++ docs/02-internal-links.md | 39 +++++++++++++++++++++++++++++++++ docs/03-embeds.md | 16 ++++++++++++++ docs/04-customizing.md | 45 +++++++++++++++++++++++++++++++++++++++ 5 files changed, 134 insertions(+), 1 deletion(-) create mode 100644 docs/01-configuration.md create mode 100644 docs/02-internal-links.md create mode 100644 docs/03-embeds.md create mode 100644 docs/04-customizing.md diff --git a/README.md b/README.md index 279d2ed..398938c 100644 --- a/README.md +++ b/README.md @@ -26,4 +26,11 @@ jobs: 3. The workflow will run automatically when you push to the main branch, after a minute or two your docs should be live at `https://.github.io/`. -The docs will include all markdown files in the `docs/` folder of your repo as well as the `Readme.md` file. \ No newline at end of file +The docs will include all markdown files in the `docs/` folder of your repo as well as the `Readme.md` file. + +More: + +- [Configuration](./docs/01-configuration.md) +- [Internal links](./docs/02-internal-links.md) +- [Embeds](./docs/03-embeds.md) +- [Customizing](./docs/04-customizing.md) diff --git a/docs/01-configuration.md b/docs/01-configuration.md new file mode 100644 index 0000000..a5eca7b --- /dev/null +++ b/docs/01-configuration.md @@ -0,0 +1,26 @@ +# Configuration + +Add a `tdocs.config.json` file to the root of your repo to override defaults: + +```json +{ + "SITE_NAME": "My Project", + "SITE_DESCRIPTION": "A short description", + "BASE_COLOR": "zinc", + "ACCENT_COLOR": "emerald", + "SEARCH_ENABLED": true, + "SHOW_THEME_TOGGLE": true, + "EXCLUDE_README": false, + "REPLACE_README_WITH_TITLE": "Introduction", + "GITHUB_URL": "https://github.com/you/your-repo" +} +``` + +All fields are optional. Socials: `TWITTER_URL`, `BLUESKY_URL`, `DISCORD_URL`, `YOUTUBE_URL`, `LINKEDIN_URL`, `FACEBOOK_URL`, `EMAIL`. + +See [`config.type.ts`](../config.type.ts) for the full list. + +## File ordering and categories + +- Prefix a filename with digits + dash to control order, e.g. `01-intro.md`, `02-setup.md`. The prefix is stripped from the URL. +- Put files in a subfolder to group them under a sidebar category, e.g. `docs/guide/01-install.md` → category "guide". diff --git a/docs/02-internal-links.md b/docs/02-internal-links.md new file mode 100644 index 0000000..cd172ba --- /dev/null +++ b/docs/02-internal-links.md @@ -0,0 +1,39 @@ +# Internal links + +Links between your markdown files need to match how tiny-docs builds URLs, or they'll 404 in the deployed site. + +## The rules + +- Write links to the **actual file path**, with the `.md` (or `.mdx`) extension. +- Paths may be relative (`./foo.md`, `../bar.md`) or absolute from the repo root (`/docs/foo.md`). +- Numeric prefixes (`01-`, `02-`) are stripped from the URL but must stay in the link. +- All URLs are lowercased. +- `README.md` maps to `/`. + +## Examples + +Given this layout: + +``` +README.md +docs/ + 01-getting-started.md + guide/ + 01-install.md + 02-usage.md +``` + +From `docs/guide/01-install.md`: + +```md +[Getting started](../01-getting-started.md) → /docs/getting-started +[Usage](./02-usage.md) → /docs/guide/usage +[Home](/README.md) → / +``` + +## Common pitfalls + +- **Don't omit the extension.** `[link](../getting-started)` won't resolve — write `[link](../getting-started.md)`. +- **Don't hand-craft the final URL.** Writing `[link](/docs/guide/usage)` skips the rewriter and breaks when `BASE` is set (project pages served under `//`). Link to the file. +- **Anchors work normally.** `[section](./usage.md#install)` is fine. +- **External links** (starting with `http`) are left untouched and open in a new tab. diff --git a/docs/03-embeds.md b/docs/03-embeds.md new file mode 100644 index 0000000..347a7ca --- /dev/null +++ b/docs/03-embeds.md @@ -0,0 +1,16 @@ +# Embeds + +Drop a URL on its own line, or use a `::directive{}` inside your markdown. + +## Built-in + +- **YouTube** — paste a youtube link, or `::youtube{#VIDEO_ID}` +- **GitHub repo card** — paste `https://github.com/owner/repo` +- **Link card** — any other URL on its own line becomes a rich link card +- **Excalidraw** — paste `https://excalidraw.com/#json=...` +- **Callouts** — GitHub-style `> [!NOTE]`, `> [!TIP]`, `> [!WARNING]`, `> [!CAUTION]`, `> [!IMPORTANT]` + +## Math and code + +- Math: `$inline$` and `$$block$$` (rendered via MathJax). +- Code blocks: Shiki highlighting with `// [!code highlight]` annotations. diff --git a/docs/04-customizing.md b/docs/04-customizing.md new file mode 100644 index 0000000..92c4c3c --- /dev/null +++ b/docs/04-customizing.md @@ -0,0 +1,45 @@ +# Customizing + +For bigger changes (styling, new components, custom embeds), vendor tiny-docs into your repo as `docs-builder/`: + +```bash +git clone --depth 1 --branch v1 https://github.com/flo-bit/tiny-docs docs-builder +rm -rf docs-builder/.git +``` + +The workflow auto-detects `docs-builder/` and uses it instead of the upstream copy. Edit anything under `docs-builder/src/` and commit — your fork ships on the next push. + +## Adding a custom component to markdown + +1. Create a component, e.g. `docs-builder/src/embeds/my-thing/MyThing.astro`. +2. Register it in `docs-builder/astro.config.ts`: + + ```ts + customEmbeds({ + embeds: [ + // ...existing + { + componentName: "MyThing", + directiveName: "mything", + importPath: "src/embeds/my-thing", + }, + ], + }), + ``` + +3. Use it in any markdown file: + + ```md + ::mything{label="hello" count=3} + ``` + +Props on the directive are passed straight to the component. For URL-triggered embeds, add a `urlMatcher` — see [`src/embeds/youtube/embed.ts`](../src/embeds/youtube/embed.ts) for an example. + +## Local development + +```bash +npm install +npm run dev +``` + +Put markdown in `docs/` and a `README.md` at the repo root, same as the deployed setup. -- 2.51.2