+I’m from Mattel!
+Well, I’m not really from Mattel. I’m actually from a smaller
+company that was purchased in a leveraged buyout.
+
+```
\ No newline at end of file
diff --git a/docs/src/basics/deploying.dj b/docs/src/foundations/deploying.dj
similarity index 100%
rename from docs/src/basics/deploying.dj
rename to docs/src/foundations/deploying.dj
diff --git a/docs/src/basics/djot.dj b/docs/src/foundations/djot.dj
similarity index 100%
rename from docs/src/basics/djot.dj
rename to docs/src/foundations/djot.dj
diff --git a/docs/src/basics/frontmatter.dj b/docs/src/foundations/frontmatter.dj
similarity index 100%
rename from docs/src/basics/frontmatter.dj
rename to docs/src/foundations/frontmatter.dj
diff --git a/docs/src/foundations/index.dj b/docs/src/foundations/index.dj
new file mode 100644
index 0000000..d8b8d34
--- /dev/null
+++ b/docs/src/foundations/index.dj
@@ -0,0 +1,4 @@
+---
+title: "Foundations"
+order: 0
+---
\ No newline at end of file
diff --git a/docs/src/basics/linking.dj b/docs/src/foundations/linking.dj
similarity index 82%
rename from docs/src/basics/linking.dj
rename to docs/src/foundations/linking.dj
index 15c989b..50abcd5 100644
--- a/docs/src/basics/linking.dj
+++ b/docs/src/foundations/linking.dj
@@ -28,4 +28,10 @@ With Djockey, you can link to it anywhere with just `#the-answer`{.language-css}
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.
\ No newline at end of file
+Shorthand link resolution doesn't work for static files, but in theory it could be made to.
+
+## Explicit links always point to specific places
+
+If you prefix your link with `./` or `/`, Djockey will always try to resolve it directly without looking up any shorthands.
+
+If you don't use a slash prefix, Djockey will still _first_ check for a document or static file at that location relative to the source document before trying to use a shorthand.
\ No newline at end of file
diff --git a/docs/src/basics/markdown.md b/docs/src/foundations/markdown.md
similarity index 100%
rename from docs/src/basics/markdown.md
rename to docs/src/foundations/markdown.md
diff --git a/docs/src/basics/sections.dj b/docs/src/foundations/sections.dj
similarity index 100%
rename from docs/src/basics/sections.dj
rename to docs/src/foundations/sections.dj
diff --git a/docs/src/basics/static_files.dj b/docs/src/foundations/static_files.dj
similarity index 100%
rename from docs/src/basics/static_files.dj
rename to docs/src/foundations/static_files.dj
diff --git a/docs/src/getting_started.dj b/docs/src/getting_started.dj
deleted file mode 100644
index f3871d0..0000000
--- a/docs/src/getting_started.dj
+++ /dev/null
@@ -1,30 +0,0 @@
----
-order: 1
----
-# Getting Started
-
-Once you've [installed Djockey](#Installation), create a file called `djockey.yaml`{.language-sh} that looks like this:
-
-```yaml
-input_dir: path-to-your-docs
-output_dir:
- html: docs_out/html
- gfm: docs_out/gfm
-site_name: "Your Name Here"
-url_root: https://where-docs-will-be-deployed
-
-html:
- footer_text: "©2024 You"
-```
-
-Now try running `npx djockey --local`{.language-sh}. Maybe it'll just work! If not, it should tell you what's wrong.
-
-## Building for local viewing vs deployment
-
-When your site is generated, all internal URLs are prefixed with the value of `urlRoot`, which is counterproductive if you want to view your site without a web server and some edits to `/etc/hosts`.
-
-To have Djockey use file URLs instead, only valid on your own machine and not requiring a web server, pass `--local`.
-
-```sh
-djockey my_docs_dir --local
-```
\ No newline at end of file
diff --git a/docs/src/index.dj b/docs/src/index.dj
index bed712a..97a4bf3 100644
--- a/docs/src/index.dj
+++ b/docs/src/index.dj
@@ -1,12 +1,85 @@
---
-title: Home
+title: Overview
---
-# Djockey
+# Overview
-Djockey is a powerful but experimental static site generator for technical writing and project documentation. The goal is to have the depth and extensibility of [Sphinx](https://www.sphinx-doc.org/en/master/) with the ease-of-use and built-in power of [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/).
+Djockey is an experimental but powerful static site generator for technical writing and project documentation. The goal is to have the depth and extensibility of [Sphinx](https://www.sphinx-doc.org/en/master/) with the ease-of-use and built-in power of [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/).
- Write [Djot](https://djot.net) or [GitHub Flavored Markdown](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax)
- Output HTML or Markdown, so your docs are readable in the GitHub interface or on a nice web site
- Rich cross-references, checked at build time
- Tree-based plugins—stop writing Markdown tokenizer hacks!
-- Biased toward static site rendering over client-side JS
\ No newline at end of file
+- De-emphasizes client-side JS, has a small core and a few small dependencies
+
+## Installation
+
+You can invoke `djockey`{.language-sh} directly with `npx`{.language-sh} or `bunx`{.language-sh}.
+
+{.tab-group}
+:::
+
+### Node
+
+```sh
+npx djockey path/to/docs
+```
+
+### Bun
+
+```sh
+bunx djockey path/to/docs
+```
+
+:::
+
+or install it in your JS project and then run it:
+
+{.tab-group}
+:::
+
+### Node
+
+```sh
+npm install djockey
+npm run djockey path/to/docs
+```
+
+### Bun
+
+```sh
+bun install djockey
+bunx djockey path/to/docs
+```
+:::
+
+### Pandoc
+
+In order to use Markdown, you must also [install Pandoc](https://pandoc.org/installing.html).
+
+## Write a bare-bones config file
+
+Once you've [installed Djockey](#Installation), create a file called `djockey.yaml`{.language-sh} that looks like this:
+
+```yaml
+input_dir: path-to-your-docs
+output_dir:
+ html: docs_out/html
+ gfm: docs_out/gfm
+site_name: "Your Name Here"
+url_root: https://where-docs-will-be-deployed
+
+html:
+ footer_text: "©2024 You"
+```
+
+Now try running `npx djockey --local`{.language-sh}. Maybe it'll just work! If not, it should tell you what's wrong.
+
+## Building for local viewing vs deployment
+
+When your site is generated, all internal URLs are prefixed with the value of `urlRoot`, which is counterproductive if you want to view your site without a web server and some edits to `/etc/hosts`.
+
+To have Djockey use file URLs instead, only valid on your own machine and not requiring a web server, pass `--local`.
+
+```sh
+djockey my_docs_dir --local
+```
\ No newline at end of file
diff --git a/docs/src/installation.dj b/docs/src/installation.dj
deleted file mode 100644
index b2e1a5d..0000000
--- a/docs/src/installation.dj
+++ /dev/null
@@ -1,47 +0,0 @@
----
-order: 0
----
-# Installation
-
-You can invoke `djockey`{.language-sh} directly with `npx`{.language-sh} or `bunx`{.language-sh}.
-
-{.tab-group}
-:::
-
-### Node
-
-```sh
-npx djockey path/to/docs
-```
-
-### Bun
-
-```sh
-bunx djockey path/to/docs
-```
-
-:::
-
-or install it in your JS project and then run it:
-
-{.tab-group}
-:::
-
-### Node
-
-```sh
-npm install djockey
-npm run djockey path/to/docs
-```
-
-### Bun
-
-```sh
-bun install djockey
-bunx djockey path/to/docs
-```
-:::
-
-## Pandoc
-
-In order to use Markdown, you must also [install Pandoc](https://pandoc.org/installing.html).
\ No newline at end of file
diff --git a/docs/src/static/custom.css b/docs/src/static/custom.css
new file mode 100644
index 0000000..766ce46
--- /dev/null
+++ b/docs/src/static/custom.css
@@ -0,0 +1,7 @@
+:root {
+ --fw-bold: 700; /* Plex doesn't go up to 800 */
+}
+
+body {
+ font-family: "IBM Plex Sans", var(--f-system);
+}
diff --git a/docs/src/why.dj b/docs/src/why.dj
index 5bd2ee0..06ff841 100644
--- a/docs/src/why.dj
+++ b/docs/src/why.dj
@@ -18,7 +18,7 @@ On the other hand, the reality is that people know Markdown and people want to w
### Other options
-The [MyST](https://myst-parser.readthedocs.io/en/latest/) flavor of Markdown uses a very effective approach to bringing the deep extensibility of [reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html) to Markdown. Unfortunately, the only existing parser is written in Python, and Djockey is not written in Python. It would be possible to try supporting MyST down the line by porting MyST's markdown-it extensions to JavaScript.
+The [MyST](https://myst-parser.readthedocs.io/en/latest/) flavor of Markdown uses a very effective approach to bringing the deep extensibility of [reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html) to Markdown. I am looking into adding MyST support to Djockey.
## Djockey
@@ -48,4 +48,16 @@ With all this in mind, Djockey:
3. Is written in TypeScript, and integrates with TypeDoc
4. Hopes to evangelize Djot, but lets you write Markdown
-The outcome is that you have an easy time writing your docs, and your users get the best possible UX.
\ No newline at end of file
+The outcome is that you have an easy time writing your docs, and your users get the best possible UX.
+
+## Alternatives to Djockey
+
+There are many wonderful documentation systems out there and Djockey tries to take inspiration from all of them. In the spirit of helping you solve your real problems, here's a list of good options with active maintenance and large communities.
+
+| | Markup | Implementation |
+|-|-|-|
+| [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) | [CommonMark](https://commonmark.org/) with custom extensions | Python |
+| [Sphinx](https://www.sphinx-doc.org/en/master/index.html) | [reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html), [MyST](https://mystmd.org) | Python |
+| [Docusaurus](https://docusaurus.io) | [CommonMark](https://commonmark.org/), [MDX](https://mdxjs.com), | JavaScript |
+| [Starlight](https://starlight.astro.build) | [Markdoc](https://markdoc.dev/docs/syntax), [MDX](https://mdxjs.com), | JavaScript |
+| [Quartz](https://quartz.jzhao.xyz/) | Markdown | JavaScript |
\ No newline at end of file
diff --git a/package-lock.json b/package-lock.json
index 0756ec6..2e18df0 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "djockey",
- "version": "0.1.1",
+ "version": "0.2.4",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "djockey",
- "version": "0.1.1",
+ "version": "0.2.4",
"license": "MIT",
"dependencies": {
"@djot/djot": "^0.3.1",
@@ -14,7 +14,6 @@
"fast-glob": "^3.3.2",
"gluegun": "^5.2.0",
"js-yaml": "^4.1.0",
- "lunr": "^2.3.9",
"mermaid": "^10.9.1",
"micromatch": "^4.0.8",
"nunjucks": "^3.2.4",
@@ -26,6 +25,7 @@
},
"devDependencies": {
"@djockey/linkmapper-typedoc": "^0.0.7",
+ "@fontsource/ibm-plex-sans": "^5.0.21",
"@jest/globals": "^29.7.0",
"@types/argparse": "^2.0.16",
"@types/d3": "^7.4.3",
@@ -39,6 +39,7 @@
"@types/nunjucks": "^3.2.6",
"@types/parse5": "^7.0.0",
"jest": "^29.7.0",
+ "lunr": "^2.3.9",
"ts-jest": "^29.2.5",
"typedoc": "^0.26.6",
"typescript": "^5.5.4"
@@ -665,6 +666,12 @@
"node": ">=17.0.0"
}
},
+ "node_modules/@fontsource/ibm-plex-sans": {
+ "version": "5.0.21",
+ "resolved": "https://registry.npmjs.org/@fontsource/ibm-plex-sans/-/ibm-plex-sans-5.0.21.tgz",
+ "integrity": "sha512-YmQJgR5rbynZPrbnfU2UojSduA8K5FV0jEq8CzTB6AU0C65ZZYrD1BX96rz/IBQx+uDeDfi4w9vP5Zb+TB5Uqw==",
+ "dev": true
+ },
"node_modules/@istanbuljs/load-nyc-config": {
"version": "1.1.0",
"resolved": "https://registry.npmjs.org/@istanbuljs/load-nyc-config/-/load-nyc-config-1.1.0.tgz",
@@ -4441,7 +4448,8 @@
"node_modules/lunr": {
"version": "2.3.9",
"resolved": "https://registry.npmjs.org/lunr/-/lunr-2.3.9.tgz",
- "integrity": "sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow=="
+ "integrity": "sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow==",
+ "dev": true
},
"node_modules/make-dir": {
"version": "4.0.0",
diff --git a/package.json b/package.json
index 660b91d..b48067a 100644
--- a/package.json
+++ b/package.json
@@ -32,7 +32,6 @@
"fast-glob": "^3.3.2",
"gluegun": "^5.2.0",
"js-yaml": "^4.1.0",
- "lunr": "^2.3.9",
"mermaid": "^10.9.1",
"micromatch": "^4.0.8",
"nunjucks": "^3.2.4",
@@ -41,6 +40,7 @@
},
"devDependencies": {
"@djockey/linkmapper-typedoc": "^0.0.7",
+ "@fontsource/ibm-plex-sans": "^5.0.21",
"@jest/globals": "^29.7.0",
"@types/argparse": "^2.0.16",
"@types/d3": "^7.4.3",
@@ -54,6 +54,7 @@
"@types/nunjucks": "^3.2.6",
"@types/parse5": "^7.0.0",
"jest": "^29.7.0",
+ "lunr": "^2.3.9",
"ts-jest": "^29.2.5",
"typedoc": "^0.26.6",
"typescript": "^5.5.4"
diff --git a/scripts/compile b/scripts/compile
index 378f530..6610fd7 100755
--- a/scripts/compile
+++ b/scripts/compile
@@ -25,15 +25,13 @@ def main():
"bun",
"build",
"--compile",
- "--minify",
- "--sourcemap",
"--asset-naming",
"[name].[ext]",
"--target",
platform,
"--outfile",
out_path,
- "./dist/cli.js",
+ "./src/cli.ts",
]
+ glob.glob("dist/templates/**/*.css", recursive=True)
+ glob.glob("dist/templates/**/*.js", recursive=True)
diff --git a/src/clientjs/index.ts b/src/clientjs/index.ts
index a7139fc..f24889c 100644
--- a/src/clientjs/index.ts
+++ b/src/clientjs/index.ts
@@ -42,5 +42,27 @@ window.onload = () => {
mermaid.run({ querySelector: ".language-mermaid" });
+ /* DJCOLLAPSE */
+
+ document.querySelectorAll(".DJCollapse_Collapser").forEach((el) => {
+ const targetID = (el as HTMLElement).dataset.collapseTarget;
+ el.addEventListener("click", (e) => {
+ const target = document.querySelector(`#${targetID}`);
+ if (!target) {
+ console.error("Can't find", `#${targetID}`);
+ return;
+ }
+ target.classList.toggle("m-collapsed");
+ el.classList.remove("m-uncollapsed");
+ el.classList.remove("m-collapsed");
+ el.classList.add(
+ target.classList.contains("m-collapsed")
+ ? "m-collapsed"
+ : "m-uncollapsed"
+ );
+ return true;
+ });
+ });
+
window.dispatchEvent(new Event("dj-onload"));
};
diff --git a/src/clientjs/search.ts b/src/clientjs/search.ts
index 57b5515..c150917 100644
--- a/src/clientjs/search.ts
+++ b/src/clientjs/search.ts
@@ -140,11 +140,11 @@ function lineToHTML(
const localStart = start - line.startInclusive;
if (localStart > lastPlainIndex) {
result.push(line.text.slice(lastPlainIndex, localStart));
- lastPlainIndex = localStart + len;
}
result.push("