flo-bit.dev
[READ-ONLY] Mirror of https://github.com/flo-bit/tiny-docs. quick setup, simple, minimalistic docs for your github project
flo-bit.dev/tiny-docs/
Merge pull request #13 from flo-bit/main
update docs
author
Florian
committer
GitHub
date
(Apr 24, 2026, 1:07 PM +0200)
commit
0a2ddd5a
0a2ddd5a80673f9b5840f8ae9779ba0c9a40a0a5
parent
56da14f5
56da14f5918be864fd9d7020594e16418e283c4f
+134
-1
+8
-1
README.md
+8
-1
README.md
···
26
26
27
27
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://<yourusername>.github.io/<yourrepo>`.
28
28
29
-
The docs will include all markdown files in the `docs/` folder of your repo as well as the `Readme.md` file.
29
+
The docs will include all markdown files in the `docs/` folder of your repo as well as the `Readme.md` file.
30
+
31
+
More:
32
+
33
+
- [Configuration](./docs/01-configuration.md)
34
+
- [Internal links](./docs/02-internal-links.md)
35
+
- [Embeds](./docs/03-embeds.md)
36
+
- [Customizing](./docs/04-customizing.md)
+26
docs/01-configuration.md
+26
docs/01-configuration.md
···
1
+
# Configuration
2
+
3
+
Add a `tdocs.config.json` file to the root of your repo to override defaults:
4
+
5
+
```json
6
+
{
7
+
"SITE_NAME": "My Project",
8
+
"SITE_DESCRIPTION": "A short description",
9
+
"BASE_COLOR": "zinc",
10
+
"ACCENT_COLOR": "emerald",
11
+
"SEARCH_ENABLED": true,
12
+
"SHOW_THEME_TOGGLE": true,
13
+
"EXCLUDE_README": false,
14
+
"REPLACE_README_WITH_TITLE": "Introduction",
15
+
"GITHUB_URL": "https://github.com/you/your-repo"
16
+
}
17
+
```
18
+
19
+
All fields are optional. Socials: `TWITTER_URL`, `BLUESKY_URL`, `DISCORD_URL`, `YOUTUBE_URL`, `LINKEDIN_URL`, `FACEBOOK_URL`, `EMAIL`.
20
+
21
+
See [`config.type.ts`](../config.type.ts) for the full list.
22
+
23
+
## File ordering and categories
24
+
25
+
- Prefix a filename with digits + dash to control order, e.g. `01-intro.md`, `02-setup.md`. The prefix is stripped from the URL.
26
+
- Put files in a subfolder to group them under a sidebar category, e.g. `docs/guide/01-install.md` → category "guide".
+39
docs/02-internal-links.md
+39
docs/02-internal-links.md
···
1
+
# Internal links
2
+
3
+
Links between your markdown files need to match how tiny-docs builds URLs, or they'll 404 in the deployed site.
4
+
5
+
## The rules
6
+
7
+
- Write links to the **actual file path**, with the `.md` (or `.mdx`) extension.
8
+
- Paths may be relative (`./foo.md`, `../bar.md`) or absolute from the repo root (`/docs/foo.md`).
9
+
- Numeric prefixes (`01-`, `02-`) are stripped from the URL but must stay in the link.
10
+
- All URLs are lowercased.
11
+
- `README.md` maps to `/`.
12
+
13
+
## Examples
14
+
15
+
Given this layout:
16
+
17
+
```
18
+
README.md
19
+
docs/
20
+
01-getting-started.md
21
+
guide/
22
+
01-install.md
23
+
02-usage.md
24
+
```
25
+
26
+
From `docs/guide/01-install.md`:
27
+
28
+
```md
29
+
[Getting started](../01-getting-started.md) → /docs/getting-started
30
+
[Usage](./02-usage.md) → /docs/guide/usage
31
+
[Home](/README.md) → /
32
+
```
33
+
34
+
## Common pitfalls
35
+
36
+
- **Don't omit the extension.** `[link](../getting-started)` won't resolve — write `[link](../getting-started.md)`.
37
+
- **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 `/<repo>/`). Link to the file.
38
+
- **Anchors work normally.** `[section](./usage.md#install)` is fine.
39
+
- **External links** (starting with `http`) are left untouched and open in a new tab.
+16
docs/03-embeds.md
+16
docs/03-embeds.md
···
1
+
# Embeds
2
+
3
+
Drop a URL on its own line, or use a `::directive{}` inside your markdown.
4
+
5
+
## Built-in
6
+
7
+
- **YouTube** — paste a youtube link, or `::youtube{#VIDEO_ID}`
8
+
- **GitHub repo card** — paste `https://github.com/owner/repo`
9
+
- **Link card** — any other URL on its own line becomes a rich link card
10
+
- **Excalidraw** — paste `https://excalidraw.com/#json=...`
11
+
- **Callouts** — GitHub-style `> [!NOTE]`, `> [!TIP]`, `> [!WARNING]`, `> [!CAUTION]`, `> [!IMPORTANT]`
12
+
13
+
## Math and code
14
+
15
+
- Math: `$inline$` and `$$block$$` (rendered via MathJax).
16
+
- Code blocks: Shiki highlighting with `// [!code highlight]` annotations.
+45
docs/04-customizing.md
+45
docs/04-customizing.md
···
1
+
# Customizing
2
+
3
+
For bigger changes (styling, new components, custom embeds), vendor tiny-docs into your repo as `docs-builder/`:
4
+
5
+
```bash
6
+
git clone --depth 1 --branch v1 https://github.com/flo-bit/tiny-docs docs-builder
7
+
rm -rf docs-builder/.git
8
+
```
9
+
10
+
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.
11
+
12
+
## Adding a custom component to markdown
13
+
14
+
1. Create a component, e.g. `docs-builder/src/embeds/my-thing/MyThing.astro`.
15
+
2. Register it in `docs-builder/astro.config.ts`:
16
+
17
+
```ts
18
+
customEmbeds({
19
+
embeds: [
20
+
// ...existing
21
+
{
22
+
componentName: "MyThing",
23
+
directiveName: "mything",
24
+
importPath: "src/embeds/my-thing",
25
+
},
26
+
],
27
+
}),
28
+
```
29
+
30
+
3. Use it in any markdown file:
31
+
32
+
```md
33
+
::mything{label="hello" count=3}
34
+
```
35
+
36
+
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.
37
+
38
+
## Local development
39
+
40
+
```bash
41
+
npm install
42
+
npm run dev
43
+
```
44
+
45
+
Put markdown in `docs/` and a `README.md` at the repo root, same as the deployed setup.