# Tiny Docs Full Documentation

# Tiny docs

quick to setup, simple, minimalistic docs for your github project

## How to use

1. Enable github pages in the repo settings. Go to _SETTINGS → PAGES → SOURCE: Github Actions_

2. Add a new github action `.github/workflows/docs.yml` with the following content:

```yaml
name: Deploy Docs

on:
    push:
        branches: [main]

permissions:
    id-token: write
    pages: write

jobs:
    docs:
        uses: flo-bit/tiny-docs/.github/workflows/tiny-docs.yml@v1
```

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>`.

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)

# 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".

# 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 `/<repo>/`). 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.

# 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.

# 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.