Merge pull request #50 from irskep/feature/extra-static-files

Various important improvements I wrote on an airplane
irskep · Sep 7, 2024 · 778c18b · 778c18b
2 parents d292598 + 40b1c1e
commit 778c18b
Show file tree

Hide file tree

Showing 47 changed files with 4,436 additions and 6,143 deletions.
diff --git a/Makefile b/Makefile
@@ -4,8 +4,8 @@ client-nocache:
 	bun build src/clientjs/index.ts --target=browser --outfile=templates/html/static/client.js --minify
 
 templates/html/static/client.js: src/clientjs/*
-	bun build src/clientjs/index.ts --target=browser --outfile=templates/html/static/client.js --minify
-	bun build src/clientjs/search.ts --target=browser --outfile=templates/html/static/search.js --minify
+	bun build src/clientjs/index.ts --target=browser --outfile=templates/html/static/client.js --minify --sourcemap
+	bun build src/clientjs/search.ts --target=browser --outfile=templates/html/static/search.js --minify --sourcemap
 
 client: templates/html/static/client.js
 

diff --git a/bun.lockb b/bun.lockb
diff --git a/docs/djockey.yaml b/docs/djockey.yaml
@@ -23,6 +23,26 @@ gfm:
 html:
   ignore_css: ["api/**/*.css"] # ignore TypeDoc CSS
   footer_text: "©2024 Steve Landey"
+  extra_static_dirs:
+    - path: ../node_modules/@fontsource/ibm-plex-sans
+      exclude_patterns: []
+      patterns:
+        - "300.css"
+        - "300-italic.css"
+        - "400.css"
+        - "400-italic.css"
+        - "600.css"
+        - "600-italic.css"
+        - "700.css"
+        - "700-italic.css"
+        - "files/ibm-plex-sans-latin-300-normal.woff2"
+        - "files/ibm-plex-sans-latin-300-italic.woff2"
+        - "files/ibm-plex-sans-latin-400-normal.woff2"
+        - "files/ibm-plex-sans-latin-400-italic.woff2"
+        - "files/ibm-plex-sans-latin-600-normal.woff2"
+        - "files/ibm-plex-sans-latin-600-italic.woff2"
+        - "files/ibm-plex-sans-latin-700-normal.woff2"
+        - "files/ibm-plex-sans-latin-700-italic.woff2"
   header_links:
     - text: "Plugin API docs"
       url: "https://steveasleep.com/djockey/api/"

diff --git a/docs/meta/api_readme.md b/docs/meta/api_readme.md
@@ -1 +1,3 @@
 This is the API reference documentation for Djockey. To read the primary docs, go to [https://steveasleep.com/djockey/](../plugins/index.html).
+
+The API is unstable and there are _no_ semver guarantees about compatibility at this time. Check back around October, or [open an issue](https://github.com/irskep/djockey/issues/new) describing your use case.
diff --git a/docs/src/alternatives.dj b/docs/src/alternatives.dj
diff --git a/docs/src/basics/custom_markup.dj b/docs/src/basics/custom_markup.dj
diff --git a/docs/src/basics/index.dj b/docs/src/basics/index.dj
diff --git a/docs/src/changelog.dj b/docs/src/changelog.dj
@@ -6,6 +6,20 @@ order: -1
 
 ## 0.2
 
+### 0.2.5 - 2024-09-06
+
+- Static file improvements
+
+  - Static files can be added from outside the doc source directory
+
+- Many changes to the default theme
+
+- Bug fixes
+
+  - Search results no longer contain duplicated text
+  - Fixed some issues with custom markup and how it's documented
+  - Probably fixed more Windows bugs
+
 ### 0.2.4 - 2024-09-04
 
 - Djockey can now run on Windows
@@ -31,11 +45,13 @@ order: -1
   - Allow putting custom links in the header
 
 - HTML improvements
+
   - OpenGraph and Twitter Card metadata
   - Site-wide search using [lunr](https://lunrjs.com)
   - Move "On this page" to a header bar on mobile instead of just disappearing
 
 - Plugin API improvements
+
   - Plugins can provide static files, perhaps based on site content (this powers search)
   - More methods can be async
   - Plugins can mark nodes as "special" and not to be touched by other plugins

diff --git a/docs/src/basics/djockey_command.dj → docs/src/djockey_command.dj b/docs/src/basics/djockey_command.dj → docs/src/djockey_command.dj
diff --git a/docs/src/basics/asides.dj → docs/src/features/asides.dj b/docs/src/basics/asides.dj → docs/src/features/asides.dj
diff --git a/docs/src/basics/configuration.dj → docs/src/foundations/configuration.dj b/docs/src/basics/configuration.dj → docs/src/foundations/configuration.dj
@@ -44,6 +44,11 @@ html:
   header_links:
     - text: "Some text"
       url: "https://a/full/url"
+  extra_static_dirs:
+    - path: "../node_modules/some_library"
+      exclude_patterns: ['**/*.ts'] # optional
+      patterns: # optional; default is '**/*'
+        - '**/*.css'
 
 gfm:
   ignore_static: ["**/*.html", "**/*.css", "**/*.js"]

diff --git a/docs/src/foundations/custom_markup.dj b/docs/src/foundations/custom_markup.dj
@@ -0,0 +1,41 @@
+---
+order: -5
+---
+# Custom markup
+
+{tag=aside .caution}
+:::
+The details of this markup are likely to change, since Djockey is experimental.
+:::
+
+## Overriding HTML tags
+
+Djot does not ([yet](https://github.com/jgm/djot/issues/240)) support arbitrary HTML tags in its input or output. Djockey works around this by postprocessing Djot's HTML output. Whenever you add a `tag=foo`{.language-text} attribute, Djockey will replace the element's tag with the attribute's value.
+
+```djot
+{tag=details} 
+:::
+{tag=summary} 
+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.
+:::
+```
+
+{tag=details} 
+:::
+{tag=summary} 
+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.
+:::
+
+```html
+<details>
+<summary>I’m from Mattel!</summary>
+<p>Well, I’m not really from Mattel. I’m actually from a smaller
+company that was purchased in a leveraged buyout.</p>
+</details>
+```
diff --git a/docs/src/basics/deploying.dj → docs/src/foundations/deploying.dj b/docs/src/basics/deploying.dj → docs/src/foundations/deploying.dj
diff --git a/docs/src/basics/djot.dj → docs/src/foundations/djot.dj b/docs/src/basics/djot.dj → docs/src/foundations/djot.dj
diff --git a/docs/src/basics/frontmatter.dj → docs/src/foundations/frontmatter.dj b/docs/src/basics/frontmatter.dj → docs/src/foundations/frontmatter.dj
diff --git a/docs/src/foundations/index.dj b/docs/src/foundations/index.dj
@@ -0,0 +1,4 @@
+---
+title: "Foundations"
+order: 0
+---
diff --git a/docs/src/basics/linking.dj → docs/src/foundations/linking.dj b/docs/src/basics/linking.dj → 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.
+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.
diff --git a/docs/src/basics/markdown.md → docs/src/foundations/markdown.md b/docs/src/basics/markdown.md → docs/src/foundations/markdown.md
diff --git a/docs/src/basics/sections.dj → docs/src/foundations/sections.dj b/docs/src/basics/sections.dj → docs/src/foundations/sections.dj
diff --git a/docs/src/basics/static_files.dj → docs/src/foundations/static_files.dj b/docs/src/basics/static_files.dj → docs/src/foundations/static_files.dj
diff --git a/docs/src/getting_started.dj b/docs/src/getting_started.dj
diff --git 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
+- 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
+```
diff --git a/docs/src/installation.dj b/docs/src/installation.dj
diff --git a/docs/src/static/custom.css 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);
+}
Original file line number	Diff line number	Diff line change
		@@ -1 +1,3 @@
		This is the API reference documentation for Djockey. To read the primary docs, go to [https://steveasleep.com/djockey/](../plugins/index.html).

		The API is unstable and there are _no_ semver guarantees about compatibility at this time. Check back around October, or [open an issue](https://github.com/irskep/djockey/issues/new) describing your use case.