New docs

docs/src/basics/frontmatter.djot

@@ -1,3 +1,6 @@
+---
+order: 1
+---
 # Front matter
 
 You can customize the title of your doc by adding YAML between `---` lines at the top, like this:
@@ -11,6 +14,8 @@ title: Custom Title
 ...
 ```
 
+This works the same way no matter what markup language you're using, meaning you can add front matter before Markdown as well.
+
 ## Title
 
 You can set `title: "My document title"` to customize how the document appears in the navigation tree and HTML page `<title>` tag.
@@ -19,6 +24,7 @@ You can set `title: "My document title"` to customize how the document appears i
 title: "A custom title"
 ```
 
+{#frontmatter-order}
 ## Order
 
 By default, documents are sorted in lexical order. But you can use an `order` value in the front matter to get more control.

docs/src/basics/linking.djot

@@ -0,0 +1,31 @@
+# Linking
+
+Everything you can do in Markdown, you can also do in Djockey. If you find that you can't, it's a bug and [you should report it](https://github.com/irskep/djockey/issues/new). But Djockey tries to make your life easier by letting you be less specific with your links, as long as they are unambiguous.
+
+## Extension or no extension, up to you
+
+If you have a doc at `life.djot`, you can link to it with either `[link text](life.djot)` or just `[link text](life)`.
+
+## Static files
+
+You can link to static files using relative paths, or absolute paths where the root is `inputDir`{.language-sh}.
+
+## Shorthand link resolution
+
+Let's say you wrote some text you need to refer to in many places across your docs, and gave it a custom identifier:
+
+```djot
+{% in /reference/answers/big-questions/life.djot %}
+{#the-answer}
+# The answer to life, the universe, and everything
+
+It's 42.
+```
+
+In any other documentation system, you'd need to link to `/reference/answers/big-questions/life#the-answer`{.language-sh}, or use a relative URL like `../../answers/big-questions/life#the-answer`{.language-sh}. But if you move `life.djot`{.language-sh} to another directory, you need to find all those links and update them.
+
+With Djockey, you can link to it anywhere with just `#the-answer`{.language-css}, and Djockey will figure out which doc it lives in. If there are two files containing a heading `#the-answer`{.language-css}, you can use just enough of the path to disambiguate the two, like `life#the-answer`{.language-sh} or `answers/big-questions/life.djot#the-answer`{.language-sh}.
+
+The goal of this feature is to make it easier to reorganize your docs on the fly. If there's any ambiguity, Djockey will warn you at build time.
+
+Shorthand link resolution doesn't work for static files, but in theory it could be made to.

docs/src/basics/sections.djot

@@ -0,0 +1,12 @@
+---
+order: 2
+---
+# Sections
+
+Djockey uses the directory tree to group documents into sections and subsections.
+
+## `index.djot`
+
+Put an `index.djot` (or `index.md`) file in any directory to customize its metadata (`title`, `order`) and give the beginning of the section some content.
+
+If `index.djot` contains front matter but no content, then the section will use the front matter, but no page will be rendered. As an example, see the "Plugins" vs "Writing with Djockey" sections on this site.

docs/src/basics/static_files.djot

@@ -1,8 +1,6 @@
 # Static Files
 
-One design goal of Djockey is to minimize the need to edit a config file.
-
-In this spirit, all files that are not markup (Markdown, Djot) are copied to the output directory.
+One design goal of Djockey is to minimize the need to edit a config file. In this spirit, all files that are not markup (i.e. not Markdown or Djot) are copied to the output directory.
 
 Any CSS and JavaScript files will be included in the HTML output. If your CSS file ends in `.light.css`{.lang-sh} or `.dark.css`{.lang-sh}, it will only be enabled for light or dark mode, respectively.
 

docs/src/contributing/building_and_running.djot

@@ -0,0 +1,18 @@
+---
+title: Building and running
+---
+# Building and running Djot locally
+
+## Using [Bun](https://bun.sh) (preferred)
+
+It's best to iterate on Djockey with Bun because you don't need to compile the TypeScript and it boots instantly.
+
+Assuming you've already installed `bun`{.language-sh}, `bun install`{.language-sh} and `bun test`{.language-sh} work as usual.
+
+`Makefile`{.language-sh} has a few shortcuts for working this way. Run `make docs`{.language-sh} to build the documentation for local browsing using Bun; this is effectively the best integration test for Djockey right now.
+
+## Using Node
+
+Djockey supports Node because most potential users already have Node installed.
+
+You can use `yarn djockey`{.language-sh} to build Djockey with `tsc`{.language-sh} and run Djockey using Node. `yarn test`{.language-sh} and `yarn test:watch`{.language-sh} will run the tests using [Jest](https://jestjs.io).

docs/src/contributing/client_side_js.djot

@@ -0,0 +1,3 @@
+# Client-side JS
+
+Djockey's built-in client-side JavaScript is written in Typescript under `src/client/js/index.ts`{.language-sh} and compiled with `bun build --target=browser`{.language-sh}. The built JS is committed to git as `templates/html/static/client.js`, in order to avoid Bun as a hard dependency for using Djockey.

docs/src/contributing/dependencies.djot

@@ -0,0 +1,20 @@
+# Dependencies
+
+Djockey's dependencies should:
+
+1. Be written by a person who knows what they are doing
+2. Have few transitive dependencies
+
+Dependencies supporting the core functionality of Djockey:
+
+- [Pandoc](https://pandoc.org) (optional): Convert to and from non-Djot formats
+- [@djot/djot](https://www.npmjs.com/package/@djot/djot): Parse Djot
+- [argparse](https://www.npmjs.com/package/argparse): Parse command-line arguments
+- [fast-glob](https://www.npmjs.com/package/fast-glob): Select files based on config options
+- [Nunjucks](https://mozilla.github.io/nunjucks/): String templates
+- [parse5](https://www.npmjs.com/package/parse5): Spec-compliant HTML5 parsing
+
+Dependencies supporting individual features:
+
+- [highlight.js](https://www.npmjs.com/package/highlight.js): Syntax highlighting (will be replaced with Shiki)
+- [Mermaid](https://mermaid.js.org): Diagram rendering

docs/src/contributing/index.djot

@@ -0,0 +1,3 @@
+---
+title: Contributing
+---

docs/src/index.djot

@@ -15,7 +15,7 @@ Djockey is a powerful but experimental static site generator for technical writi
 ### Documentation
 
 - [x] Why Djockey? Why Djot?
-- [ ] Developing/contributing
+- [x] Developing/contributing
 - [ ] Plugin API docs
 - [ ] How to use plugins
 - [x] Config reference
@@ -27,10 +27,11 @@ Djockey is a powerful but experimental static site generator for technical writi
 - [ ] Switch from highlight.js to Shiki so we can use [the Djot Textmate grammar](https://github.com/ryanabx/djot-vscode/blob/main/syntaxes/djot.tmLanguage.json)
 - [ ] Fancy logging and error reporting
 - [ ] Finish CSS stylesheets
+- [ ] Multi-tab code blocks/divs
+- [ ] `defaultLanguage`{.language-plaintext} in front matter
 - [x] Syntax highlighting, Mermaid, Graphviz
 - [x] Literal symbol parsing
 - [x] Dark mode
-- [ ] Multi-tab code blocks/divs
 - [x] Sections with and without self-docs have the same appearance but only one is clickable
 
 ### Harder stuff