Skip to content

Commit 51b99ae

Browse files
CollierCZCollierCZ
committed
📝 Add basic docs site with content from ReadMe
1 parent 49791f0 commit 51b99ae

34 files changed

+2474
-660
lines changed

‎.gitignore

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,11 @@
1+
# Built files
12
dist
3+
.svelte-kit
4+
build
5+
6+
# Dependencies
27
node_modules
38
.npmrc
49

10+
# Test files
511
coverage

‎packages/docs/markdoc/nodes/fence.js

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
import Markdoc from '@markdoc/markdoc'
2+
3+
const fence = {
4+
render: 'CodeBlock',
5+
attributes: {
6+
content: {
7+
type: String,
8+
},
9+
language: {
10+
type: String,
11+
},
12+
process: {
13+
...Markdoc.nodes.fence.attributes.process,
14+
default: false
15+
},
16+
},
17+
async transform(node, config) {
18+
const attributes = node.transformAttributes(config)
19+
const children = node.transformChildren(config)
20+
const code =
21+
children.length > 0
22+
? children.join()
23+
: attributes.content
24+
25+
const codeWithoutEmptyLastLine = code.replace(/\n$/, '')
26+
27+
return new Markdoc.Tag(this.render, {
28+
lang: attributes.language,
29+
code: codeWithoutEmptyLastLine,
30+
})
31+
},
32+
}
33+
34+
export default fence

‎packages/docs/markdoc/nodes/index.js

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
import fence from './fence.js'
2+
3+
const nodes = {
4+
fence,
5+
}
6+
7+
export default nodes

‎packages/docs/package.json

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
{
2+
"name": "collier.cz",
3+
"version": "1.0.0",
4+
"scripts": {
5+
"dev": "vite dev",
6+
"dev:open": "vite dev --open",
7+
"build": "vite build",
8+
"preview": "vite preview",
9+
"check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
10+
"check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
11+
"lint": "prettier . --check && eslint .",
12+
"format": "prettier --write .",
13+
"test": "vitest run",
14+
"test:coverage": "vitest run --coverage"
15+
},
16+
"devDependencies": {
17+
"@fontsource/fira-mono": "^5.1.0",
18+
"@markdoc/markdoc": "^0.5.2",
19+
"@sveltejs/adapter-static": "^3.0.6",
20+
"@sveltejs/kit": "2.6.0",
21+
"@sveltejs/vite-plugin-svelte": "^5.1.0",
22+
"@tailwindcss/typography": "^0.5.15",
23+
"@types/eslint": "^9.6.1",
24+
"@types/eslint-config-prettier": "^6.11.3",
25+
"@types/eslint__js": "^8.42.3",
26+
"@types/node": "^22.15.32",
27+
"@vitest/coverage-v8": "^2.1.8",
28+
"autoprefixer": "^10.4.20",
29+
"globals": "^15.14.0",
30+
"markdoc-svelte": "file:../markdoc-svelte",
31+
"shiki": "^1.24.3",
32+
"svelte": "^5.15.0",
33+
"svelte-check": "^4.1.1",
34+
"svelte-preprocess": "^6.0.3",
35+
"tailwindcss": "^3.4.17",
36+
"typescript": "^5.7.2",
37+
"vite": "^6.3.5",
38+
"vitest": "^2.1.8"
39+
},
40+
"type": "module"
41+
}

‎packages/docs/src/app.css

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
@tailwind base;
2+
@tailwind components;
3+
@tailwind utilities;

‎packages/docs/src/app.html

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
<!doctype html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="utf-8" />
5+
<meta name="viewport" content="width=device-width, initial-scale=1" />
6+
%sveltekit.head%
7+
</head>
8+
<body data-sveltekit-preload-data="hover">
9+
<div style="display: contents">%sveltekit.body%</div>
10+
</body>
11+
</html>

‎packages/docs/src/content/docs/customize-markdoc.mdoc

Whitespace-only changes.

‎packages/docs/src/content/docs/examples/images.mdoc

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
title: Enhanced images
3+
---
4+
5+
Use the [enhanced-img plugin](https://svelte.dev/docs/kit/images#sveltejs-enhanced-img) with images in your files processed by `markdown-svelte`.
6+
To do so, customize the default images Node with a custom Svelte component.
7+
See an example [custom node](../schema/nodes).

‎packages/docs/src/content/docs/examples/index-page.mdoc

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
---
2+
title: Index page example
3+
---
4+
5+
Each processed page exports a slug based on the file name.
6+
This is a convenient way to generate an index page without reaching into the document.
7+
8+
Glob import these slugs as data for your index page.
9+
For example, if all of your pages end with the extension `.md`,
10+
Add the following to `src/routes/blog/+page.ts`:
11+
12+
```typescript
13+
import type { MarkdocModule } from "markdoc-svelte";
14+
15+
import type { PageLoad } from "./$types";
16+
17+
const markdownModules = import.meta.glob("$lib/markdown/*.md");
18+
19+
export const load: PageLoad = async () => {
20+
const content = await Promise.all(
21+
Object.values(markdownModules).map(async (importModule) => {
22+
// Dynamically import each module
23+
const module = (await importModule()) as MarkdocModule;
24+
// Pass only slug and frontmatter to the page data
25+
return {
26+
slug: module.slug,
27+
frontmatter: module.frontmatter,
28+
};
29+
}),
30+
);
31+
return { content };
32+
};
33+
```
34+
35+
Then use this data to build an index page at `src/routes/blog/+page.svelte`:
36+
37+
```svelte
38+
<script lang="ts">
39+
import type { PageProps } from './$types';
40+
41+
let { data }: PageProps = $props();
42+
const { content } = data;
43+
</script>
44+
45+
<h1>Table of Contents</h1>
46+
<ul>
47+
{#each content as item, i (item.slug)}
48+
<li class={'item-' + i}>
49+
<a href="/{item.slug}">
50+
<h2>{item.frontmatter?.title || item.slug}</h2>
51+
{#if item.frontmatter?.description}
52+
<span>{item.frontmatter.description}</span>
53+
{/if}
54+
{#if item.frontmatter?.published}
55+
<span>{item.frontmatter.published}</span>
56+
{/if}
57+
</a>
58+
</li>
59+
{/each}
60+
</ul>
61+
```

‎packages/docs/src/content/docs/examples/toc.mdoc

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
title: Table of contents
3+
---
4+
5+
Each proccessed page automatically exports a `headings` property with all headings on the page and IDs for each.
6+
Add IDs with [annotations](https://markdoc.dev/docs/syntax#annotations) or they are generated automatically.
7+
Use this list to generate a table of contents for the page, as in the following example:
8+
9+
```svelte
10+
<script lang="ts">
11+
import type { PageProps } from './$types';
12+
13+
let { data }: PageProps = $props();
14+
const { frontmatter, headings } = data.page;
15+
16+
// Filter only h1 and h2 headings
17+
const filteredHeadings = headings?.filter((heading) => heading.level <= 2) ?? [];
18+
</script>
19+
20+
<svelte:head>
21+
<title>{data.page.frontmatter?.title ?? 'Undefined title'}</title>
22+
</svelte:head>
23+
24+
{#if filteredHeadings.length > 0}
25+
<ul>
26+
{#each filteredHeadings as heading}
27+
<li>
28+
<a href={`#${heading.id}`}>{heading.text}</a>
29+
</li>
30+
{/each}
31+
</ul>
32+
{/if}
33+
34+
<data.page.default />
35+
```

‎packages/docs/src/content/docs/frontmatter.mdoc

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
title: Frontmatter
3+
---
4+
5+
Optionally define YAML frontmatter in your file.
6+
Then use it in your content with the `$frontmatter` variable.
7+
8+
```markdown
9+
---
10+
title: Why I switched to Markdoc
11+
description: What the benefits of Markdoc are and how to take advantage of them.
12+
---
13+
14+
# {% $frontmatter.title %}
15+
```
16+
17+
You can also access the frontmatter in your Svelte page components.
18+
Get it from the data you defined in `+page.ts`:
19+
20+
```svelte
21+
<script lang="ts">
22+
import type { PageProps } from './$types';
23+
24+
let { data }: PageProps = $props();
25+
</script>
26+
27+
<svelte:head>
28+
<title>{data.page.frontmatter?.title ?? 'Default title'}</title>
29+
<meta name="description" content={data.page.frontmatter?.description ?? 'Default description'} />
30+
</svelte:head>
31+
32+
<data.page.default />
33+
```

‎packages/docs/src/content/docs/get-started.mdoc

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
---
2+
title: Get started
3+
---
4+
5+
## Install
6+
7+
Install `markdoc-svelte` in your SvelteKit project.
8+
9+
```bash
10+
npm install markdoc-svelte
11+
```
12+
13+
Amend your SvelteKit config in `svelte.config.js` to:
14+
15+
- Process files with the extensions you choose (such as `.mdoc` and `.md`).
16+
- Include the preprocessor.
17+
18+
```javascript
19+
import { markdocPreprocess } from "markdoc-svelte";
20+
21+
/** @type {import('@sveltejs/kit').Config} */
22+
const config = {
23+
extensions: [".svelte", ".mdoc", ".md"],
24+
preprocess: [markdocPreprocess()],
25+
};
26+
```
27+
28+
## Basic example
29+
30+
Create a directory to hold your markdoc files: `src/lib/markdoc`
31+
32+
In that directory (at `src/lib/markdown/content.md`), add an example with basic Markdown syntax:
33+
34+
```markdown
35+
---
36+
title: Hello World
37+
---
38+
39+
# Hello World
40+
41+
This is a file that is processed by `markdoc-svelte`.
42+
43+
![Alt text](/path/to/image.jpg)
44+
```
45+
46+
Dynamically import all files in the directory using a catchall route at `src/routes/[...catchall]/+page.ts`:
47+
48+
```typescript
49+
import { error } from "@sveltejs/kit";
50+
import type { PageLoad } from "./$types";
51+
import type { MarkdocModule } from "markdoc-svelte";
52+
53+
export const load: PageLoad = async ({ params }) => {
54+
const slug = params.catchall;
55+
try {
56+
const page = (await import(`$lib/markdown/${slug}.md`)) as MarkdocModule;
57+
return { page };
58+
} catch {
59+
throw error(404, `No corresponding file found for the slug "${slug}"`);
60+
}
61+
};
62+
```
63+
64+
Render the imported file as a Svelte component in a file at `src/routes/[...catchall]/+page.svelte`:
65+
66+
```svelte
67+
<script lang="ts">
68+
import type { PageProps } from './$types';
69+
70+
let { data }: PageProps = $props();
71+
</script>
72+
73+
<svelte:head>
74+
<title>{data.page.frontmatter?.title ?? 'Undefined title'}</title>
75+
</svelte:head>
76+
77+
<data.page.default />
78+
```
79+
80+
Run your dev server and visit `/content` to see the rendered file.

‎packages/docs/src/content/docs/options.mdoc

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
title: Preprocessor options
3+
---
4+
5+
The following table shows all of the options available for `markdoc-svelte`:
6+
7+
| Option | Type | Default | Description |
8+
| ----------------- | ------------------- | -------------------------------- | ------------------------------------------------------------------------- |
9+
| `comments` | boolean | `true` | Enable [Markdown comments](https://spec.commonmark.org/0.30/#example-624) |
10+
| `components` | string | `"$lib/components"` | Svelte components directory for custom nodes and tags |
11+
| `extensions` | string[] | `[".mdoc", ".md"]` | Files to process with Markdoc |
12+
| `functions` | Config['functions'] | - | [Functions config](./schema/functions) |
13+
| `layout` | string | - | Default layout for all processed Markdown files |
14+
| `linkify` | boolean | `false` | Auto-convert bare URLs to links |
15+
| `nodes` | Config['nodes'] | - | [Nodes config](./schema/nodes) |
16+
| `partials` | string | - | [Partials](./schema/partials) directory path |
17+
| `schema` | string | `["./markdoc", "./src/markdoc"]` | Schema directory path |
18+
| `tags` | Config['tags'] | - | [Tags config](./schema/tags) |
19+
| `typographer` | boolean | `false` | Enable [typography replacements](#typographer) |
20+
| `validationLevel` | ValidationLevel | `"error"` | [Validation strictness level](#validation-level) |
21+
| `variables` | Config['variables'] | - | [Variables config](./schema/variables) |
22+
23+
24+
## Typographer
25+
26+
Choose whether to turn on typographic replacements from [markdown-it](https://github.com/markdown-it/markdown-it).
27+
See the options in action at the [markdown-it demo](https://markdown-it.github.io/)
28+
(select or deselect `typographer`).
29+
Defaults to false.
30+
31+
## Validation level
32+
33+
The preprocessor validates whether the Markdoc is valid.
34+
By default, it throws an error on files for issues at the `error` or `critical` level.
35+
To debug, you can set the level to a lower level to stop the build for any errors at that level or above.
36+
Possible values in ascending order: `debug`, `info`, `warning`, `error`, `critical`.

0 commit comments

Comments
 (0)