Merge pull request #171 from TorstenDittmann/feat-new-docs

feat: new docs

apps/documentation/.gitignore

@@ -0,0 +1,25 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+doc_build

apps/documentation/docs/_meta.json

@@ -0,0 +1,7 @@
+[
+    {
+        "text": "Guide",
+        "link": "/guide/install",
+        "activeMatch": "/guide/"
+    }
+]

apps/documentation/docs/guide/_meta.json

@@ -0,0 +1 @@
+["install", "configuration", "nodes", "tags", "layouts", "partials", "advanced"]

apps/documentation/docs/guide/advanced.md

@@ -0,0 +1,86 @@
+# Advanced
+
+## Display lists of pages
+
+If you want to get a list of all .markdoc files in a directory, for example in a blog you want to list all posts, you can use the `import.meta.glob` function.
+
+```md
+---
+title: My Blog Post
+description: This is a blog post and it is awesome.
+date: 2021-01-01
+---
+
+# My Blog Post
+
+...
+```
+
+```js title="+page.server.js"
+export function load() {
+    const modules = import.meta.glob('./blog/*.markdoc', {
+        eager: true,
+    });
+
+    const posts = Object.entries(modules).map(([filepath, module]) => {
+        const { frontmatter } = module;
+        return {
+            filepath,
+            title: frontmatter.title,
+            description: frontmatter.description,
+            date: frontmatter.date,
+        };
+    });
+
+    return {
+        posts,
+    };
+}
+```
+
+## Visual Studio Code `experimental`
+
+The preprocessor automatically generates a schema file at `.svelte-kit/markdoc_schema.js` which can be used with the official [Visual Studio Code Extension](https://marketplace.visualstudio.com/items?itemName=Stripe.markdoc-language-support).
+
+In the `markdoc.config.json` [configuration file](https://github.com/markdoc/language-server#configuration-quickstart) point to the schema file:
+
+```json
+[
+    {
+        "id": "my-site",
+        "path": "docs/content",
+        "schema": {
+            "path": ".svelte-kit/markdoc_schema.js",
+            "type": "esm",
+            "property": "default",
+            "watch": true
+        }
+    }
+]
+```
+
+## Markdoc configuration
+
+You can configure the underlying Markdoc compiler by passing a [configuration object](https://markdoc.dev/docs/config#options).
+
+```js title="svelte.config.js"
+markdoc({
+    config: {
+        variables: {
+            name: 'Dr. Mark',
+            frontmatter: {
+                title: 'Configuration options',
+            },
+        },
+        functions: {
+            includes: {
+                transform(parameters, config) {
+                    const [array, value] = Object.values(parameters);
+
+                    return Array.isArray(array) ? array.includes(value) : false;
+                },
+            },
+        },
+    },
+});
+```

apps/documentation/docs/guide/configuration.md

@@ -0,0 +1,82 @@
+# Configuration
+
+You can pass the configuration to the preprocessor in the `svelte.config.js` like this:
+
+```js title="svelte.config.js"
+import { markdoc } from 'svelte-markdoc-preprocess';
+
+const config = {
+    preprocess: [
+        vitePreprocess(),
+        markdoc({
+            // configuration here
+        }),
+    ],
+};
+```
+
+## Options
+
+#### `extensions`
+
+**Type**: `string[]`
+
+**Default**: `['.markdoc', '.mdoc', '.markdown', '.md']`
+
+Extensions to be processed.
+
+#### `nodes`
+
+**Type**: `string | null`
+
+**Default**: `null`
+
+Absoulute path to the `.svelte` file exporting components for nodes.
+
+#### tags
+
+**Type**: `string | null`
+
+**Default**: `null`
+
+Absoulute path to the `.svelte` file exporting components for tags.
+
+#### partials
+
+**Type**: `string`
+
+**Default**: `null`
+
+Absoulute path to the folder for partials.
+
+#### generateSchema
+
+**Type**: `boolean`
+
+**Default**: `true`
+
+Generate schema files under `./svelte-kit/markdoc-schema.json` to be used with the official [Visual Studio Code extension](https://marketplace.visualstudio.com/items?itemName=Stripe.markdoc-language-support).
+
+#### layouts
+
+**Type**: `Record<string, string> | null`
+
+**Default**: `null`
+
+Layouts to be used for pages.
+
+#### validationThreshold
+
+**Type**: `"error" | "debug" | "info" | "warning" | "critical"`
+
+**Default**: `error`
+
+The threshold for validation errors to stop the build.
+
+#### allowComments
+
+**Type**: `boolean`
+
+**Default**: `false`
+
+Allow comments in the markdown files.

apps/documentation/docs/guide/install.md

@@ -0,0 +1,24 @@
+# Install
+
+Install the package:
+
+```sh
+npm i -D svelte-markdoc-preprocess
+```
+
+Add the preprocessor and new extensions to your `svelte.config.js`:
+
+```javascript title="svelte.config.js"
+import { markdoc } from 'svelte-markdoc-preprocess';
+
+const config = {
+    preprocess: [vitePreprocess(), markdoc()],
+    extensions: ['.markdoc', '.svelte'],
+};
+```
+
+```md title="+page.markdoc"
+# I am a heading
+
+I am a paragraph with **bold** words. But you can also use Svelte Components:
+```

apps/documentation/docs/guide/layouts.md

@@ -0,0 +1,78 @@
+# Layouts
+
+You can define layouts in the `markdoc` options.
+
+```js title="svelte.config.js"
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+markdoc({
+    layouts: {
+        default: join(
+            dirname(fileURLToPath(import.meta.url)),
+            './src/lib/Layout.svelte',
+        ),
+    },
+});
+```
+
+Layout files are basically Svelte components with a slot. The `default` slot is used for all files.
+
+```html title="./src/lib/Layout.svelte"
+<nav>...</nav>
+
+<slot />
+```
+
+### Named
+
+If you want to use a named layout for a specific file, you can specify it in the frontmatter.
+
+```js title="svelte.config.js"
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+markdoc({
+    layouts: {
+        default: join(
+            dirname(fileURLToPath(import.meta.url)),
+            './src/lib/Layout.svelte',
+        ),
+        some_other_layout: join(
+            dirname(fileURLToPath(import.meta.url)),
+            './src/lib/SomeOtherLayout.svelte',
+        ),
+    },
+});
+```
+
+```md title="+page.markdoc"
+---
+layout: some_other_layout
+---
+
+# some other content
+```
+
+### Props
+
+Layouts will be passed the frontmatter as props from the Markdoc file.
+
+```html title="./src/lib/Layout.svelte"
+<script>
+    export let title;
+    export let description;
+</script>
+
+<svelte:head>
+    <title>{title}</title>
+    <meta name="description" content="{description}" />
+</svelte:head>
+```
+
+```md title="+page.markdoc"
+---
+title: Lorem ipsum
+description: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+---
+```

apps/documentation/docs/guide/nodes.md

@@ -0,0 +1,33 @@
+# Nodes
+
+You can use Svelte components in your markdown files, you can define Svelte Component for each node.
+
+Create a Svelte file and export Svelte components with the same name as the node from the module context.
+
+```html title="src/lib/Nodes.svelte"
+<script context="module">
+    export { default as Heading } from './Heading.svelte';
+</script>
+```
+
+```js title="svelte.config.js"
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+markdoc({
+    nodes: join(
+        dirname(fileURLToPath(import.meta.url)),
+        './src/lib/Nodes.svelte',
+    ),
+});
+```
+
+```html title="./src/lib/Heading.svelte"
+<script>
+    export let level;
+</script>
+
+<svelte:element this="{`h${level}`}"><slot /></svelte:element>
+```
+
+You can find a list of available nodes [here](https://markdoc.dev/docs/nodes#built-in-nodes).

apps/documentation/docs/guide/partials.md

@@ -0,0 +1,41 @@
+# Partials
+
+You pass a directory to the configuration and it will automatically load all files to be used as [partials](https://markdoc.dev/docs/partials).
+
+```js title="svelte.config.js"
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+markdoc({
+    partials: join(
+        dirname(fileURLToPath(import.meta.url)),
+        './src/lib/partials',
+    ),
+});
+```
+
+```md title="./src/lib/partials/header.md"
+# My header
+```
+
+Here's an example of including the `header.md` file as a partial.
+
+`{% partial file="header.md" /%}`
+
+```md title="./src/routes/+page.markdoc"
+{ % partial file="header.md" /% }
+```
+
+### Passing variables
+
+Partials are like any other tags, so you can pass variables as attributes to them such as:
+
+```md title="./src/routes/+page.markdoc"
+{ % partial file="header.md" variables={name: "My header name"} /% }
+```
+
+and access the variables as you would in a regular Markdoc document:
+
+```md title="./src/lib/partials/header.md"
+# { % $name % }
+```