{"id":15984727,"url":"https://github.com/jaredreisinger/zspec","last_synced_at":"2025-10-03T14:43:02.127Z","repository":{"id":146779082,"uuid":"456830889","full_name":"JaredReisinger/zspec","owner":"JaredReisinger","description":"Updated documentation ideas for The Z-Machine Standard","archived":false,"fork":false,"pushed_at":"2024-06-25T06:02:58.000Z","size":1024,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-02-10T05:26:11.477Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://zspec.jaredreisinger.com","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JaredReisinger.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-02-08T07:41:09.000Z","updated_at":"2024-06-25T06:03:02.000Z","dependencies_parsed_at":null,"dependency_job_id":"df6c4d37-355d-4cd1-ba20-d477e662d27e","html_url":"https://github.com/JaredReisinger/zspec","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JaredReisinger%2Fzspec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JaredReisinger%2Fzspec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JaredReisinger%2Fzspec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JaredReisinger%2Fzspec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JaredReisinger","download_url":"https://codeload.github.com/JaredReisinger/zspec/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247249602,"owners_count":20908211,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-08T02:10:18.079Z","updated_at":"2025-10-03T14:43:02.061Z","avatar_url":"https://github.com/JaredReisinger.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Z-Machine Standards Document 1.1 (annotated)\n\nAnother presentation of Graham Nelson’s [_The Z-Machine Standards Document_](http://inform-fiction.org/zmachine/standards/z1point1), using [`Antora`](https://antora.org) as the book renderer. Rather than reiterate the reasons for doing this _here_, take a look at [the editor’s note itself](https://zspec.jaredreisinger.com/zz01-editors-note) (or [the source](./modules/ROOT/pages/ZZ01-editors-note.adoc)).\n\nUse `npm run dev` for edit/refresh local developement.\n\n## Components\n\n- `modules`: the Antora \"content source\" for the document\n\n- `supplemental-ui`: UI-specific customization for the presentation\n\n- `extensions`: custom Antora/Asciidoctor.js extensions (for date formatting, etc.)\n\n## Technical details\n\nI started by converting the original HTML document to Markdown, which was then fed into [`mdbook`](https://rust-lang.github.io/mdBook/index.html) to generate the site. This functioned well, but Markdown is really insufficient for the task of “real” documentation. Sooner or later you run into something that Markdown simply can’t represent. There are various and competing Markdown variants, but those all feel like they are just postponing the problem. (And don’t get me wrong, I love Markdown for the majority of basic notes/readme-style docs!) I found [AsciiDoc](https://docs.asciidoctor.org/asciidoc/latest/) and [`asciidoctor`](https://asciidoctor.org/) and began the conversion from Markdown to AsciiDoc. Fairly quickly, my desire for a shared navigation pane along with multi-page presentation meant I needed to look a bit more… and I found [Antora](https://antora.org/), which is what the current iteration is using.\n\nFor hosting, I’m taking advantage of [Netlify](https://netlify.com)’s free hosting for static sites.\n\n---\n\n## TO-DO\n\n- [x] clean up images (from low-res GIF to something sharper) _(The architecture diagram in the overview is now an SVG.. the chapter images/icons aren't really important enough to update, and could probably even be omitted entirely.)_\n\n- [ ] ~~Change layout to “inline” the section numbers? The original format “wastes” a lot of vertical space on lines that contain _only_ section numbers. I’m pretty sure there are better technical documentation layouts than that.~~ _(Changing the layout would require explicitly labelling the anchors, which seems like overkill.  This is more of a \"completely redo the document\" kind of thing.)_\n\n- [x] Improve the generated anchor references? Periods are omitted, which means that “1.12″ and”1.1.2″ are both converted to “#112…” that’s just a bad design. Better would be for any consecutive non-alphanumeric characters to become `-` or `_`.\n\n- [ ] ~~I looked at using a real section mark (§ ) instead of `S`, but `mdbook` can’t handle bolding it… but perhaps with a “real” section indicator the bolding is unnecessary?~~ _(We could, but **S** is just fine for now, and does keep consistent with the canonical version.)_\n\n- [x] Markdown appears to be insufficient for the documentation formatting I want (like showing my annotations); I’m currently leaning towards [AsciiDoc](https://docs.asciidoctor.org/asciidoc/latest/) and [Asciidoctor](https://docs.asciidoctor.org/asciidoctor/latest/) instead. For now, however, I’m going to complete the Markdown conversion.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjaredreisinger%2Fzspec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjaredreisinger%2Fzspec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjaredreisinger%2Fzspec/lists"}