Repository navigation
docs: add the documentation website and agent instructions - #25
Merged
Merged
Conversation
Adopts the Allors documentation standard for Allors Excel: a docs/ website built with Astro and Starlight, with twelve pages for users and maintainers, Markdown exports and an llms.txt index generated from the same pages, and a documentation workflow that validates the /excel/ and / deployment paths without publishing. The tooling is copied from the Allors Documents adoption at 62794a7, which carries the fixes made since the Allors3 original (forward-slash link-checker messages, focusable code blocks, the version label from version.json). The export integration reads the index title and description from site.mjs so that it holds no project text; the decision record lists every project-specific change. Validated on 2026-10-19 from docs/ for both base paths: npm test, npm run check, npm run build, npm run check:links and npm run test:browser. The tutorial was run from a clean directory against a clone of the repository; the repository build and tests were run with task test, and the Excel passes' failure on a machine whose Excel shows the Microsoft 365 privacy dialog is recorded in Build and test.
AGENTS.md points agents at the human documentation, the writing guide and the build and test instructions. The README becomes an introduction with absolute links to the pages, because it is packed into the NuGet packages, and says that the published 1.0.73 packages predate the renames on main.
The two CI legs install Office and take a quarter of an hour each. Changes limited to docs/, the documentation workflow or AGENTS.md are validated by the Documentation workflow instead. README.md still runs CI because it is part of every package.
The Excel-DNA and VSTO excerpts now match the source line for line, with the omitted error handling named instead of silently dropped.
koenvanexem
added a commit
that referenced
this pull request
Oct 19, 2026
Follow up on the review of #25. Distinguish awaited and discarded callback Tasks, document headless range-parser and cell-coordinate limitations, and describe decimal conversion bounds and exceptions without promising type preservation. These changes document existing runtime behaviour rather than altering the library. Wait for Mermaid rendering before both keyboard-navigation overflow assertions so the checks do not measure the unrendered diagram source. Validated on 2026-10-19: 21 tooling tests; Astro check with no diagnostics; builds, 718 links and 14 browser tests at both / and /excel/; 20 repeated keyboard-navigation checks; task compile; 46 headless tests; chunk tests on net462 and net10.0 plus the net462 console runner. Real Excel tests were not rerun because the existing Microsoft 365 privacy dialog blocks unattended execution.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adopts the Allors documentation standard for Allors Excel.
docs/website built with Astro and Starlight, with twelve pages for users and maintainers: a tutorial run against a clone of the repository, an explanation of the virtual workbook, how-to guides for hosting a program in Excel and for binding cells, an API reference, a packages page, terminology, and maintainer pages on architecture, build and test, writing documentation and the decision record.llms.txtindex generated from the same pages, and aDocumentationworkflow that validates the/excel/and/deployment paths without publishing.AGENTS.mdwith agent instructions that point to the human documentation, and a README reduced to an introduction with absolute links, because it is packed into the NuGet packages. The README says that the published1.0.73packages predate the renames onmain.CIworkflow skips changes limited todocs/, the documentation workflow andAGENTS.md; its two legs install Office and take a quarter of an hour each.The tooling is copied from the Allors Documents adoption at
62794a7, which carries the fixes made since the Allors3 original: forward-slash link-checker messages, focusable code blocks and the version label fromversion.json. The export integration reads the index title and description fromsite.mjs, so it holds no project text. The decision record lists every project-specific change and the findings for the shared-tooling question.Validation on 2026-10-19, from
docs/for both base paths:npm test(21 tests),npm run check,npm run build(12 pages),npm run check:links(703 links, 0 errors) andnpm run test:browser(14 tests). The tutorial was run from a clean directory and its page shows the observed output.task testbuilt every project; the headless pass and the chunk tests passed, and the two Excel passes failed on a machine whose Excel opens with the Microsoft 365 privacy dialog, as Build and test records. CI passes all 149 tests.Recorded in the documentation, not fixed: the text colour of a
Styleis never written to Excel, the VSTO sample ribbon names callbacks its class does not implement, the headless worksheet's custom properties arenull, the package metadata's project URL points at the Documents repository, and the Excel test fixture leaks its instance when its constructor fails.