Skip to content

Commit 1d5d7df

Browse files
gbro3ngbro3n
committed
Github pages docs deployment
1 parent 17a33a6 commit 1d5d7df

43 files changed

Lines changed: 4471 additions & 29 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/ci.yml‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,22 @@ on:
77
branches: [main]
88

99
jobs:
10+
test-common:
11+
runs-on: ubuntu-latest
12+
steps:
13+
- uses: actions/checkout@v4
14+
- uses: actions/setup-node@v4
15+
with:
16+
node-version: '20'
17+
cache: 'npm'
18+
cache-dependency-path: common/package-lock.json
19+
- run: npm ci
20+
working-directory: common
21+
- run: npm test
22+
working-directory: common
23+
1024
test-vs-code-extension:
25+
needs: test-common
1126
runs-on: ubuntu-latest
1227
steps:
1328
- uses: actions/checkout@v4
@@ -16,7 +31,63 @@ jobs:
1631
node-version: '20'
1732
cache: 'npm'
1833
cache-dependency-path: vs-code-extension/package-lock.json
34+
- run: npm ci
35+
working-directory: common
1936
- run: npm ci
2037
working-directory: vs-code-extension
2138
- run: npm test
2239
working-directory: vs-code-extension
40+
41+
test-html-conversion:
42+
needs: test-common
43+
runs-on: ubuntu-latest
44+
steps:
45+
- uses: actions/checkout@v4
46+
- uses: actions/setup-node@v4
47+
with:
48+
node-version: '20'
49+
cache: 'npm'
50+
cache-dependency-path: html-conversion/package-lock.json
51+
- run: npm ci
52+
working-directory: common
53+
- run: npm ci
54+
working-directory: html-conversion
55+
- run: npm test
56+
working-directory: html-conversion
57+
58+
build-docs:
59+
needs: test-html-conversion
60+
runs-on: ubuntu-latest
61+
steps:
62+
- uses: actions/checkout@v4
63+
- uses: actions/setup-node@v4
64+
with:
65+
node-version: '20'
66+
cache: 'npm'
67+
cache-dependency-path: html-conversion/package-lock.json
68+
- run: npm ci
69+
working-directory: common
70+
- run: npm ci
71+
working-directory: html-conversion
72+
- run: npm run build
73+
working-directory: html-conversion
74+
- run: npm run convert -- --input ../docs-src/pages --output ../docs
75+
working-directory: html-conversion
76+
- uses: actions/upload-pages-artifact@v3
77+
if: github.ref == 'refs/heads/main' && github.event_name == 'push'
78+
with:
79+
path: docs
80+
81+
deploy-pages:
82+
needs: build-docs
83+
if: github.ref == 'refs/heads/main' && github.event_name == 'push'
84+
runs-on: ubuntu-latest
85+
permissions:
86+
pages: write
87+
id-token: write
88+
environment:
89+
name: github-pages
90+
url: ${{ steps.deployment.outputs.page_url }}
91+
steps:
92+
- id: deployment
93+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
# Agents files
22

3-
agents/
3+
agents/*
4+
!agents/
5+
!agents/TECHNICAL.md
46
AGENTS.md
57

68
# Sync files

docs/TECHNICAL.md renamed to AGENTS_TECHNICAL.md

Lines changed: 41 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -115,18 +115,57 @@ This document explains the internal architecture, algorithms, and design decisio
115115

116116
## Overview
117117

118-
as-notes is a VS Code extension that turns `[[double bracket]]` text in markdown files into navigable links. Each wikilink maps to a `.md` file in the same directory. The extension provides highlighting, click navigation, hover tooltips, auto-creation of missing pages, and automated rename synchronisation between link text and filenames.
118+
as-notes is a monorepo containing a VS Code extension, a shared wikilink parsing library, and an HTML conversion utility.
119+
120+
### Repository structure
121+
122+
```
123+
as-notes/
124+
├── common/ # Shared wikilink parsing library
125+
│ ├── src/
126+
│ │ ├── Wikilink.ts # Wikilink data model
127+
│ │ ├── WikilinkService.ts # Stack-based parser + segment computation
128+
│ │ ├── MarkdownItWikilinkPlugin.ts # markdown-it inline rule plugin
129+
│ │ └── index.ts # Barrel export
130+
│ └── test/
131+
│ └── WikilinkService.test.ts # 23 tests
132+
├── vs-code-extension/ # VS Code extension (imports from common via file: dep)
133+
├── html-conversion/ # CLI: markdown+wikilinks → static HTML
134+
│ ├── src/
135+
│ │ ├── convert.ts # CLI entry point (--input, --output)
136+
│ │ └── FileResolver.ts # Flat-file wikilink→href resolver
137+
│ └── test/
138+
│ └── FileResolver.test.ts # 16 tests
139+
└── docs-src/ # Documentation source (AS Notes workspace)
140+
└── pages/ # Markdown files converted to docs/
141+
```
142+
143+
### Cross-package dependency
144+
145+
`vs-code-extension` and `html-conversion` both depend on `as-notes-common` via `"file:../common"` in `package.json`. This creates a symlink in `node_modules/as-notes-common` — no npm publish needed. esbuild resolves the symlink and bundles the shared code.
146+
147+
### VS Code extension
119148

120149
The extension is built with:
121150

122151
- **TypeScript 5.7**, strict mode, ES2022 target
123152
- **esbuild** for bundling via custom `build.mjs` (`src/extension.ts` → `dist/extension.js`, CJS format, `vscode` external). Includes a custom `sqlJsCacheResetPlugin` that patches sql.js at bundle time — see [Manual rebuild](#manual-rebuild)
124153
- **sql.js ^1.14.0** — WASM SQLite for the persistent index (zero native dependencies, works in VS Code remote/Codespaces)
125-
- **vitest 3.x** for unit tests (219 tests across 8 test files)
154+
- **vitest 3.x** for unit tests (448 tests across 13 test files)
126155
- **VS Code API ^1.85.0** (`DocumentLinkProvider`, `HoverProvider`, `TextEditorDecorationType`, `WorkspaceEdit`)
127156

128157
The build script (`build.mjs`) copies the `sql-wasm.wasm` binary to `dist/` alongside the bundled extension.
129158

159+
### HTML conversion utility
160+
161+
A standalone CLI tool for converting an AS Notes workspace (markdown files with `[[wikilinks]]`) into static HTML:
162+
163+
- **FileResolver** — scans a directory for `.md` files, builds a case-insensitive filename→href lookup map (same semantics as the extension: spaces URL-encoded). Tracks missing targets during resolution and exposes them via `getMissingTargets()` so placeholder pages can be generated.
164+
- **convert.ts** — CLI entry point: parses `--input <dir>` and `--output <dir>` args, wipes the output directory, runs markdown-it with the shared `wikilinkPlugin`, wraps each page in an HTML shell with `<nav>` sidebar, writes `.html` files. After converting real pages, generates placeholder pages for any missing wikilink targets with a "This page has not been created yet" message and the same nav sidebar.
165+
- **Nav generation** — `index.html` appears as "Home", other pages sorted alphabetically. Minimal semantic markup with class names (`site-nav`, `nav-current`, `content`, `missing-page`) for future CSS styling
166+
- **CI integration** — the `build-docs` job in `.github/workflows/ci.yml` builds and runs the conversion: `docs-src/pages/` → `docs/`
167+
- **npm script** — `npm run convert -- --input <dir> --output <dir>` runs the built CLI from `dist/convert.js`
168+
130169
---
131170

132171
## Persistent index

‎README.md‎

Lines changed: 32 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -465,22 +465,44 @@ To resolve, check your workspace settings and `.asnotesignore` file. If the file
465465

466466
## Development
467467

468+
The repository is structured as a monorepo with three packages:
469+
470+
| Package | Description |
471+
|---|---|
472+
| `common/` | Shared wikilink parsing library (`Wikilink`, `WikilinkService`, `MarkdownItWikilinkPlugin`) |
473+
| `vs-code-extension/` | The VS Code extension |
474+
| `html-conversion/` | CLI utility that converts an AS Notes notebook (markdown + wikilinks) to static HTML |
475+
476+
Documentation source lives in `docs-src/` (an AS Notes workspace). The `html-conversion` tool converts it to `docs/`.
477+
478+
### VS Code Extension
479+
468480
```bash
469-
# Install dependencies
481+
cd vs-code-extension
470482
npm install
483+
npm run build # Build the extension
484+
npm run watch # Watch mode (rebuilds on changes)
485+
npm test # Run unit tests
486+
npm run lint # Type-check
487+
```
471488

472-
# Build the extension
473-
npm run build
489+
### HTML Conversion
474490

475-
# Watch mode (rebuilds on changes)
476-
npm run watch
491+
```bash
492+
cd html-conversion
493+
npm install
494+
npm run build
495+
npm run convert -- --input ../docs-src/pages --output ../docs
496+
```
477497

478-
# Run unit tests
479-
npm test
498+
The conversion:
499+
- Scans the input directory for `.md` files
500+
- Resolves `[[wikilinks]]` to relative `.html` links
501+
- Generates a `<nav>` sidebar on each page
502+
- Creates placeholder pages for missing wikilink targets with a "This page has not been created yet" message
503+
- Wipes the output directory before each run
480504

481-
# Type-check
482-
npm run lint
483-
```
505+
In CI, the `build-docs` job runs the same steps automatically on push/PR to `main` (see `.github/workflows/ci.yml`).
484506

485507
### Debugging
486508

‎agents‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Subproject commit 6ddbf3fb003a37eb2930cb9b0593c67476fda6a9

‎common/.gitignore‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Dependencies
2+
node_modules/
3+
4+
# Build output
5+
dist/
6+
7+
# OS files
8+
.DS_Store
9+
Thumbs.db

0 commit comments

Comments
 (0)