zaine/org_web
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

updates
All checks were successful
Build Org Website / build (push) Successful in 38s
Details

Browse Source
This commit is contained in:
gitea-actions
2026-08-20 11:32:08 +01:00
parent 8dbeca7570
commit 65885dbb3a
19 changed files with 132 additions and 114 deletions
Download Patch File Download Diff File Expand all files Collapse all files

112
README.md
View File

@@ -9,7 +9,7 @@ This README is the central technical guide for the repository: start here for ar
The application has three boundaries:
1. **Site source (this repository):** Org/Markdown content, Emacs Lisp publishing code, CSS, JavaScript, images, and build tooling.
2. **Static output (`output/`):** generated HTML, copied assets, and `search-index.json`. This is the deployable website, not the source of truth.
2. **Static output (**`output/`**):** generated HTML, copied assets, and `search-index.json`. This is the deployable website, not the source of truth.
3. **Runtime services (outside this repository):** the authoring service and the same-origin APIs used by interactive pages. The static site remains readable without them, but the relevant dynamic features will not work.
```mermaid
@@ -25,26 +25,26 @@ flowchart LR
## Repository map
| Path | Purpose | Source or generated? |
| --- | --- | --- |
| `index.org` | Home page source | Source |
| `blogs/` | Dated personal writing, grouped by year/month | Source, except generated list pages |
| `posts/` | Longer-lived posts; `posts/career/` has its own index | Source, except generated list pages |
| `home/` | Utility and dashboard-style pages | Source, except `categories.org` |
| `play/` | Interactive and experimental pages | Source |
| `rl/` | Browser-local Resource Loader SPA | Source |
| `lima/` | Org or Markdown pages with special attachment handling | Source, except `lima-list.org` |
| `assets/` | Browser code, styles, fonts, images, and content manifests | Mostly source; some manifests/scripts are generated externally |
| `lisp/` | Modular Emacs Lisp publishing system | Source |
| `lisp/tests/` | ERT tests for the publishing logic | Source |
| `tags/` | Per-tag Org pages created during a build | Generated |
| `recently-updated.org` | Recent-content list created during a build | Generated |
| `sitemap.org` and `*-list.org` | Sitemap/list sources created by `org-publish` | Generated |
| `output/` | Complete publish output | Generated |
| `.org-timestamps/` | Incremental publish cache | Generated |
| `.packages/` | Repository-local Emacs package directory | Generated/cache |
| `build-logs/` | Gitea build monitoring script, cache, and logs | Mixed; script is source, logs/cache are runtime data |
| `docs/` | Historical/design notes for individual features | Supplemental; this README is the central engineering guide |
| Path | Purpose | Source or generated? |
|----------------------------|------------------------------------------------------------|----------------------------------------------------------------|
| `index.org` | Home page source | Source |
| `blogs/` | Dated personal writing, grouped by year/month | Source, except generated list pages |
| `posts/` | Longer-lived posts; `posts/career/` has its own index | Source, except generated list pages |
| `home/` | Utility and dashboard-style pages | Source, except `categories.org` |
| `play/` | Interactive and experimental pages | Source |
| `rl/` | Browser-local Resource Loader SPA | Source |
| `lima/` | Org or Markdown pages with special attachment handling | Source, except `lima-list.org` |
| `assets/` | Browser code, styles, fonts, images, and content manifests | Mostly source; some manifests/scripts are generated externally |
| `lisp/` | Modular Emacs Lisp publishing system | Source |
| `lisp/tests/` | ERT tests for the publishing logic | Source |
| `tags/` | Per-tag Org pages created during a build | Generated |
| `recently-updated.org` | Recent-content list created during a build | Generated |
| `sitemap.org` and `*-list.org` | Sitemap/list sources created by `org-publish` | Generated |
| `output/` | Complete publish output | Generated |
| `.org-timestamps/` | Incremental publish cache | Generated |
| `.packages/` | Repository-local Emacs package directory | Generated/cache |
| `build-logs/` | Gitea build monitoring script, cache, and logs | Mixed; script is source, logs/cache are runtime data |
| `docs/` | Historical/design notes for individual features | Supplemental; this README is the central engineering guide |
## Build architecture
@@ -67,19 +67,19 @@ flowchart TD
### Build modules
| Module | Responsibility |
| --- | --- |
| `build-core.el` | Logging, timing, local package bootstrap, and base Org configuration |
| `build-assets.el` | Shared CSS/JS `<head>` manifest, cache-busted asset URLs, and asset synchronization |
| `build-html.el` | Custom HTML backend, page shell, Mermaid export, macros, body classes, tags, and comments |
| `build-projects.el` | `org-publish-project-alist` for the main site, posts, blogs, career, tags, Lima, categories, and assets |
| `build-runner.el` | Cache integrity, generated inputs, publishing, and build metrics |
| `build-lima.el` | Lima Org/Markdown conversion and neighboring attachment copying |
| `build-comments.el` | Comment opt-in detection, comment HTML injection, and comment-page manifest generation |
| `sitemaps.el` | Main Mermaid sitemap and specialized blog/post/career/category lists |
| `tags.el` | Tag discovery, generated tag pages, and tag markup in exported HTML |
| `recently-updated.el` | Recent page list generation using `#+DATE` with mtime fallback |
| `sidenotes.el` | Sidenote suppression rules for special page layouts |
| Module | Responsibility |
|---------------------|-------------------------------------------------------------------------------------------------------|
| `build-core.el` | Logging, timing, local package bootstrap, and base Org configuration |
| `build-assets.el` | Shared CSS/JS `<head>` manifest, cache-busted asset URLs, and asset synchronization |
| `build-html.el` | Custom HTML backend, page shell, Mermaid export, macros, body classes, tags, and comments |
| `build-projects.el` | `org-publish-project-alist` for the main site, posts, blogs, career, tags, Lima, categories, and assets |
| `build-runner.el` | Cache integrity, generated inputs, publishing, and build metrics |
| `build-lima.el` | Lima Org/Markdown conversion and neighboring attachment copying |
| `build-comments.el` | Comment opt-in detection, comment HTML injection, and comment-page manifest generation |
| `sitemaps.el` | Main Mermaid sitemap and specialized blog/post/career/category lists |
| `tags.el` | Tag discovery, generated tag pages, and tag markup in exported HTML |
| `recently-updated.el` | Recent page list generation using `#+DATE` with mtime fallback |
| `sidenotes.el` | Sidenote suppression rules for special page layouts |
The main `org-main` project recursively publishes every Org file, while narrower projects provide specialized sitemap behavior and options. That overlap is intentional: Org's timestamp cache prevents unnecessary repeated work in normal incremental builds.
@@ -139,25 +139,25 @@ Then open `http://127.0.0.1:8000`. Dynamic `/api/...` features require the exter
### Make targets
| Command | Effect |
| --- | --- |
| `make build` | Run the Emacs publishing pipeline |
| `make search` | Create/update `output/search-index.json`, creating `.venv` when needed |
| `make` | Set machine-specific permissions, remove `output/`, build, index search, and remove `.venv` |
| `make clean-output` | Delete the configured output directory |
| `make test-elisp` | Run the Emacs Lisp ERT suite |
| `make test` | Run tests in the sibling authoring-service repository |
| `make norm` | Move Emacs backup files into `backups/` |
| `make help` | List supported targets |
| Command | Effect |
|-------------------|-----------------------------------------------------------------------------------------|
| `make build` | Run the Emacs publishing pipeline |
| `make search` | Create/update `output/search-index.json`, creating `.venv` when needed |
| `make` | Set machine-specific permissions, remove `output/`, build, index search, and remove `.venv` |
| `make clean-output` | Delete the configured output directory |
| `make test-elisp` | Run the Emacs Lisp ERT suite |
| `make test` | Run tests in the sibling authoring-service repository |
| `make norm` | Move Emacs backup files into `backups/` |
| `make help` | List supported targets |
### Build environment variables
| Variable | Meaning |
| --- | --- |
| Variable | Meaning |
|-----------------------|--------------------------------------------------------------------------|
| `SITE_OUTPUT_DIR=/path` | Publish somewhere other than `output/`; the Python indexer respects it too |
| `SITE_FORCE=1` | Republish every file instead of using Org timestamps |
| `SITE_DRY=1` | Generate/prepare inputs but skip `org-publish-all` |
| `SITE_CLEAN=1` | Delete output and `.org-timestamps/`, then force a full publish |
| `SITE_FORCE=1` | Republish every file instead of using Org timestamps |
| `SITE_DRY=1` | Generate/prepare inputs but skip `org-publish-all` |
| `SITE_CLEAN=1` | Delete output and `.org-timestamps/`, then force a full publish |
The build checks that assets and an entry page exist in the output. If the output is missing or incomplete while timestamps remain, it clears the timestamp cache and forces a full publish to avoid a falsely successful incremental build.
@@ -269,12 +269,12 @@ Third-party browser dependencies are vendored: Lunr, Mermaid, BiggerPicture, and
The published HTML is static, but some browser modules rely on same-origin APIs:
| Feature | Browser module | Runtime endpoint |
| --- | --- | --- |
| Comments and replies | `features/comments.js` | `GET /api/comments/:slug`, `POST /api/comments` |
| Notes board | `pages/notes.js` | `/api/notes` |
| Wird tracker | `pages/wird-tracker.js` | `/api/wird`, `/api/wird/motalah`, `/api/calibre/books` |
| Competency board | `pages/competency-status-board.js` | `/api/competencies/items...` |
| Feature | Browser module | Runtime endpoint |
|----------------------|----------------------------------|--------------------------------------------------|
| Comments and replies | `features/comments.js` | `GET /api/comments/:slug`, `POST /api/comments` |
| Notes board | `pages/notes.js` | `/api/notes` |
| Wird tracker | `pages/wird-tracker.js` | `/api/wird`, `/api/wird/motalah`, `/api/calibre/books` |
| Competency board | `pages/competency-status-board.js` | `/api/competencies/items...` |
These APIs are not implemented here. Production routing must serve `output/` and proxy `/api/` to the appropriate backend. When changing an endpoint contract, coordinate the static client and its external service.
@@ -401,4 +401,4 @@ Static file serving does not provide `/api/...`. Run/proxy the relevant external
### The full `make` command fails outside the production host
`make` runs a hard-coded permission helper with `sudo`. Use `make build` followed by `make search`, or the portable commands above, on another machine.
`make` runs a hard-coded permission helper with `sudo`. Use `make build` followed by `make search`, or the portable commands above, on another machine.