diff --git a/.dockerignore b/.dockerignore index 358db729..f3d7c86b 100644 --- a/.dockerignore +++ b/.dockerignore @@ -12,6 +12,7 @@ build/ dist/ storybook-static/ docs-static/ +blog-static/ coverage/ # Development files @@ -137,4 +138,7 @@ package-lock.json DEVELOPMENT.md DEPLOYMENT.md SECURITY.md -CLAUDE.md \ No newline at end of file +CLAUDE.md +blog/node_modules/ +blog/dist/ +blog/.astro/ diff --git a/.github/workflows/blog.yml b/.github/workflows/blog.yml new file mode 100644 index 00000000..a7fc7073 --- /dev/null +++ b/.github/workflows/blog.yml @@ -0,0 +1,108 @@ +name: Blog builder + +# The blog is built in the cluster from pushed articles (blog/scripts/publish.ts) and made +# live from the private blog desk (blog/desk/). This workflow tests both and publishes two +# images from blog/Dockerfile: ghcr.io/-blog (builder) and ghcr.io/-blog-desk. +# It runs when the blog or the portfolio source it imports (tokens, components, links) changes. +on: + push: + branches: [master] + paths: + - blog/** + - src/** + - .github/workflows/blog.yml + pull_request: + paths: + - blog/** + - src/** + - .github/workflows/blog.yml + workflow_dispatch: + +permissions: + contents: read + +jobs: + test: + name: Test the blog builder + runs-on: ubuntu-latest + defaults: + run: + working-directory: blog + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-node@v4 + with: + node-version: 22 + cache: yarn + cache-dependency-path: blog/yarn.lock + + - name: Install + run: yarn install --frozen-lockfile + + - name: Publish script and desk tests + run: yarn test + + - name: Type check + run: yarn typecheck + env: + ASTRO_TELEMETRY_DISABLED: 1 + + - name: Build the sample articles + run: yarn build:fixtures + env: + ASTRO_TELEMETRY_DISABLED: 1 + NODE_ENV: production + + image: + name: Publish the ${{ matrix.target }} image + needs: test + if: github.event_name != 'pull_request' + runs-on: ubuntu-latest + permissions: + contents: read + packages: write + strategy: + matrix: + include: + - target: builder + image: blog + description: Builds the blog from pushed articles and switches the live site atomically. Never reads the vault. + - target: desk + image: blog-desk + description: Private blog desk - previews vault drafts with the real build and pushes them to the blog. Runs behind SSO. + steps: + - uses: actions/checkout@v4 + + - uses: docker/setup-buildx-action@v3 + + - uses: docker/login-action@v3 + with: + registry: ghcr.io + username: ${{ github.actor }} + password: ${{ secrets.GITHUB_TOKEN }} + + - id: meta + uses: docker/metadata-action@v5 + with: + images: ghcr.io/${{ github.repository }}-${{ matrix.image }} + tags: | + type=sha,format=short + type=raw,value=latest,enable={{is_default_branch}} + labels: | + org.opencontainers.image.title=derekmackley.com/blog ${{ matrix.target }} + org.opencontainers.image.description=${{ matrix.description }} + + - name: Build and push + uses: docker/build-push-action@v5 + with: + context: . + file: blog/Dockerfile + target: ${{ matrix.target }} + push: true + tags: ${{ steps.meta.outputs.tags }} + labels: ${{ steps.meta.outputs.labels }} + build-args: BUILD_ID=${{ github.sha }} + platforms: linux/amd64 + cache-from: type=gha,scope=blog-${{ matrix.target }} + cache-to: type=gha,mode=max,scope=blog-${{ matrix.target }} diff --git a/.gitignore b/.gitignore index 8b231169..4b77a1bc 100644 --- a/.gitignore +++ b/.gitignore @@ -11,6 +11,7 @@ node_modules/ # production /build /docs-static +/blog-static /logs # misc @@ -64,4 +65,6 @@ dist/ **/vendor **/.bundle **/.jekyll-cache -**/_site \ No newline at end of file +**/_site/blog/node_modules +/blog/dist +/blog/.astro diff --git a/blog/Dockerfile b/blog/Dockerfile new file mode 100644 index 00000000..cc6bd026 --- /dev/null +++ b/blog/Dockerfile @@ -0,0 +1,62 @@ +# Two images from one build, kept apart on purpose: +# +# builder (default) builds derekmackley.com/blog from pushed articles and switches the +# live site atomically (scripts/publish.ts). Mounts only blog-content. +# Never sees the Obsidian vault. +# desk the private blog desk (desk/server.ts): lists posts in the vault, +# previews them with the real build, pushes them to blog-content. +# Runs behind single sign-on with the vault mounted read-only. +# +# Build context is the repository root (the blog imports the portfolio's design tokens +# and React components from ../src): +# docker build -f blog/Dockerfile -t developer-portfolio-blog . +# docker build -f blog/Dockerfile --target desk -t developer-portfolio-blog-desk . + +# syntax=docker/dockerfile:1 +FROM node:22-alpine AS base + +ENV NODE_ENV=production \ + ASTRO_TELEMETRY_DISABLED=1 + +WORKDIR /app/blog + +# Dependencies first, for layer caching. Dev tools (astro check, typescript) are not needed. +COPY blog/package.json blog/yarn.lock ./ +RUN yarn install --frozen-lockfile --production --non-interactive \ + && yarn cache clean + +# The shared portfolio source the blog imports (tokens, props-only components, site links) +COPY src /app/src +COPY blog/ /app/blog/ + +# Prove the build works before either image is published (the sample articles only) +RUN ARTICLES_DIR=/app/blog/fixtures/articles SITE_DIR=/tmp/selftest node scripts/publish.ts \ + && test -f /tmp/selftest/current/sample-article-format/index.html \ + && rm -rf /tmp/selftest /tmp/blog-* + +# BUILD_ID makes a new image rebuild the site even when the articles did not change +ARG BUILD_ID=dev +ENV BUILD_ID=${BUILD_ID} + +# --------------------------------------------------------------------------- +FROM base AS desk + +# The two icons the preview pages link to (served from the portfolio root on the live site) +COPY public/apple-touch-icon.png public/favicon-32.png /app/public/ + +ENV VAULT_DIR=/vault \ + CONTENT_DIR=/content \ + DESK_AUTH_HEADER=x-authentik-username \ + PORT=8080 +EXPOSE 8080 +USER 1000:1000 +ENTRYPOINT ["node", "desk/server.ts"] + +# --------------------------------------------------------------------------- +FROM base AS builder + +ENV ARTICLES_DIR=/content/articles \ + SITE_DIR=/content/site +# Same uid/gid as the vault jobs and the volume's VolSync mover +USER 1000:1000 +ENTRYPOINT ["node", "scripts/publish.ts"] diff --git a/blog/astro.config.mjs b/blog/astro.config.mjs new file mode 100644 index 00000000..2848dc8a --- /dev/null +++ b/blog/astro.config.mjs @@ -0,0 +1,44 @@ +// @ts-check +import { fileURLToPath } from 'node:url'; +import { defineConfig } from 'astro/config'; +import react from '@astrojs/react'; +import sitemap from '@astrojs/sitemap'; +import rehypeCallouts from 'rehype-callouts'; +import { unified } from '@astrojs/markdown-remark'; + +// The portfolio's source, shared read-only: design tokens and props-only React molecules +const portfolioSrc = fileURLToPath(new URL('../src', import.meta.url)); + +export default defineConfig({ + site: 'https://derekmackley.com', + // Served by the portfolio's Express server from the blog-content volume + base: '/blog', + trailingSlash: 'ignore', + build: { format: 'directory' }, + outDir: process.env.BLOG_OUT_DIR ?? './dist', + // The publisher's root filesystem is read-only; keep caches in /tmp there + cacheDir: process.env.BLOG_CACHE_DIR ?? './node_modules/.astro', + integrations: [react(), sitemap()], + markdown: { + processor: unified({ + // Raw HTML in an article is not rendered; articles are Markdown only + remarkRehype: { allowDangerousHtml: false }, + rehypePlugins: [[rehypeCallouts, { theme: 'github' }]], + }), + shikiConfig: { theme: 'github-dark-dimmed', wrap: true }, + }, + vite: { + resolve: { + alias: { + '@': portfolioSrc, + '@molecules': `${portfolioSrc}/components/molecules`, + '@atoms': `${portfolioSrc}/components/atoms`, + '@utils': `${portfolioSrc}/utils`, + '@tokens': `${portfolioSrc}/assets/css/design-system`, + }, + // Components under ../src must use this package's React, not a second copy + dedupe: ['react', 'react-dom', 'framer-motion'], + }, + server: { fs: { allow: ['..'] } }, + }, +}); diff --git a/blog/desk/desk.css b/blog/desk/desk.css new file mode 100644 index 00000000..85b61778 --- /dev/null +++ b/blog/desk/desk.css @@ -0,0 +1,189 @@ +/* Blog desk: the portfolio's tokens (inlined above by the server) plus these few rules. */ + +body { + background: var(--color-background); + color: var(--color-text); + font-family: var(--font-family-inter); +} + +.desk { + max-width: var(--container-max-width); + margin: 0 auto; + padding: var(--section-gap) var(--spacing-4); +} + +.desk-header { + margin-bottom: var(--spacing-5); +} + +.desk-kicker, +.desk-mono, +.desk-path, +.desk-detail, +.desk-status { + font-family: var(--font-family-jetbrains); + letter-spacing: var(--letter-spacing-technical); +} + +.desk-kicker { + margin: 0 0 var(--spacing-2); + font-size: var(--font-size-sm); + color: var(--color-cyan); +} + +.desk h1 { + margin: 0; + font-size: var(--font-size-2xl); + color: var(--color-white); +} + +.desk h2 { + margin: 0 0 var(--spacing-2); + font-size: var(--font-size-lg); + color: var(--color-white); +} + +.desk-lede { + margin: var(--spacing-2) 0 0; + color: var(--color-text-muted); +} + +.desk-flash { + padding: var(--spacing-3) var(--spacing-4); + background: var(--surface-inset); + border: 1px solid var(--surface-border-strong); + border-left: 3px solid var(--color-primary); + border-radius: var(--radius-card); +} + +.desk-table-wrap { + overflow-x: auto; + background: var(--surface-card); + border: 1px solid var(--surface-border); + border-radius: var(--radius-card); +} + +.desk-table { + width: 100%; + border-collapse: collapse; + font-size: var(--font-size-sm); +} + +.desk-table th, +.desk-table td { + padding: var(--spacing-3); + text-align: left; + vertical-align: top; + border-bottom: 1px solid var(--surface-divider); +} + +.desk-table th { + font-family: var(--font-family-jetbrains); + font-size: var(--font-size-xs); + font-weight: var(--font-weight-medium); + text-transform: uppercase; + letter-spacing: var(--letter-spacing-technical); + color: var(--color-text-muted); +} + +.desk-title { + display: block; + font-weight: var(--font-weight-semibold); + color: var(--color-white); +} + +.desk-path, +.desk-detail { + display: block; + margin-top: var(--spacing-1); + font-size: var(--font-size-xs); + color: var(--color-text-muted); +} + +.desk-status { + display: inline-block; + padding: 0 var(--spacing-2); + font-size: var(--font-size-xs); + border: 1px solid var(--surface-border); + border-radius: var(--radius-chip); +} + +.desk-status--live { color: var(--color-success); border-color: var(--color-success); } +.desk-status--pending { color: var(--color-primary); border-color: var(--color-primary); } +.desk-status--changed { color: var(--color-warning); border-color: var(--color-warning); } +.desk-status--blocked { color: var(--color-text-muted); } +.desk-status--off { color: var(--color-text); } + +.desk-warn { + margin: var(--spacing-1) 0 0; + font-size: var(--font-size-xs); + color: var(--color-warning); +} + +.desk-actions { + display: flex; + flex-wrap: wrap; + gap: var(--spacing-2); + align-items: center; +} + +.desk-actions form, +.desk-orphans form { + margin: 0; +} + +.desk-button { + min-height: var(--control-height-sm); + padding: 0 var(--spacing-3); + font: inherit; + font-size: var(--font-size-xs); + font-family: var(--font-family-jetbrains); + color: var(--color-primary); + background: transparent; + border: 1px solid var(--surface-border-strong); + border-radius: var(--radius-control); + cursor: pointer; +} + +.desk-button:hover { + border-color: var(--color-primary); +} + +.desk-button:focus-visible, +.desk-link:focus-visible { + outline: none; + box-shadow: var(--ring-focus); +} + +.desk-button--primary { + color: var(--color-gray-900); + background: var(--color-primary); + border-color: var(--color-primary); +} + +.desk-button--quiet { + color: var(--color-text-muted); +} + +.desk-link { + font-size: var(--font-size-xs); + color: var(--color-primary); +} + +.desk-orphans { + margin-top: var(--spacing-6); +} + +.desk-orphans ul { + display: flex; + flex-direction: column; + gap: var(--spacing-2); + padding: 0; + list-style: none; +} + +.desk-orphans li { + display: flex; + gap: var(--spacing-3); + align-items: center; +} diff --git a/blog/desk/desk.test.ts b/blog/desk/desk.test.ts new file mode 100644 index 00000000..38f1a64c --- /dev/null +++ b/blog/desk/desk.test.ts @@ -0,0 +1,272 @@ +import { describe, it, beforeEach, afterEach } from 'node:test'; +import assert from 'node:assert/strict'; +import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'; +import { createServer, type Server } from 'node:http'; +import { tmpdir } from 'node:os'; +import path from 'node:path'; +import { convertBody, describeNote, exportNote, indexImages, slugify, stripComments } from './export.ts'; +import { linkTargets, listPosts, pushArticle, pushedArticles, safeNotePath, unpushArticle } from './store.ts'; +import { createDesk } from './server.ts'; + +let root: string; +let vault: string; +let content: string; + +const post = (fm: string, draft: string, extra = '') => + `---\n${fm.trim()}\n---\n\n# Heading\n\n## Thesis\nprivate planning ${extra}\n\n## Draft\n${draft}\n`; + +const write = (rel: string, text: string | Buffer) => { + const full = path.join(vault, rel); + mkdirSync(path.dirname(full), { recursive: true }); + writeFileSync(full, text); +}; + +const READY = `type: blog-post +title: "Watering on a Timer" +summary: "What a drip timer taught me." +description: "Vault-only note about the post idea." +published: 2024-05-12 +topics: [Gardening, Drip Irrigation] +stage: edit +pillar: "Gardening" +related: + - "[[Personal/Finance/Budget]]"`; + +beforeEach(() => { + root = mkdtempSync(path.join(tmpdir(), 'desk-test-')); + vault = path.join(root, 'vault'); + content = path.join(root, 'content'); + mkdirSync(content); + write('Personal/Finance/Budget.md', '---\ntype: note\n---\nSECRET budget numbers'); + write('Attachments/Garden/timer.png', Buffer.from('png-bytes')); + write('Projects/Blog/000 Blog Index.md', '---\ntype: index\n---\n# Index'); + write('Projects/Blog/Ideas/Gardening/Watering on a Timer.md', post(READY, [ + 'The timer runs at dawn. See [[Personal/Finance/Budget|my budget]] and [[Raised Beds]].', + '', + '![[timer.png|The timer]]', + '', + '> [!info] Worth knowing', + '> Drip lines clog.', + '', + '%% do not publish this aside %%', + '', + '', + '```md', + '[[Not a link]] %% stays %%', + '```', + ].join('\n'))); + write('Projects/Blog/Ideas/Gardening/Raised Beds.md', post('type: blog-post\ntitle: Raised Beds\nsummary: Beds.\npublished: 2024-05-01', 'Beds text.')); + write('Projects/Blog/Ideas/Cooking/Half Done.md', post('type: blog-post\nstage: idea', '')); +}); + +afterEach(() => rmSync(root, { recursive: true, force: true })); + +describe('export', () => { + it('slugifies titles', () => { + assert.equal(slugify('Waiting Is Not Failing!'), 'waiting-is-not-failing'); + assert.equal(slugify('Crème brûlée & you'), 'creme-brulee-you'); + }); + + it('lists what blocks a note', () => { + const info = describeNote('x.md', post('type: blog-post\ntitle: x', '')); + assert.deepEqual(info.problems, ['add summary: (the public one-line description)', 'add published: YYYY-MM-DD', 'write the post under ## Draft']); + assert.deepEqual(describeNote('y.md', post('type: blog-post\ntitle: Topics\nsummary: d\npublished: 2024-01-01', 'x')).problems, + ['"topics" is reserved; set slug:']); + }); + + it('exports only the public fields and the draft', () => { + const a = exportNote(vault, 'Projects/Blog/Ideas/Gardening/Watering on a Timer.md', new Map()); + const index = a.files.get('index.md')!.toString(); + assert.equal(a.slug, 'watering-on-a-timer'); + assert.deepEqual(a.meta, { title: 'Watering on a Timer', description: 'What a drip timer taught me.', published: '2024-05-12', topics: ['gardening', 'drip-irrigation'] }); + for (const leak of ['Budget', 'related', 'pillar', 'private planning', 'do not publish', 'nor this', 'SECRET', 'Vault-only']) { + assert.ok(!index.includes(leak) || index.includes('my budget'), `leaked: ${leak}`); + } + assert.ok(!index.includes('Personal/Finance')); + assert.ok(!index.includes('private planning')); + }); + + it('turns links to unpublished notes into plain text and to live posts into links', () => { + const a = exportNote(vault, 'Projects/Blog/Ideas/Gardening/Watering on a Timer.md', new Map([['Raised Beds', 'raised-beds']])); + const index = a.files.get('index.md')!.toString(); + assert.match(index, /See my budget and \[Raised Beds\]\(\/blog\/raised-beds\/\)\./); + }); + + it('ships embedded images next to the article', () => { + const a = exportNote(vault, 'Projects/Blog/Ideas/Gardening/Watering on a Timer.md', new Map()); + assert.match(a.files.get('index.md')!.toString(), /!\[The timer\]\(\.\/timer\.png\)/); + assert.equal(a.files.get('timer.png')!.toString(), 'png-bytes'); + }); + + it('takes the whole draft, including its own ## headings', () => { + write('Projects/Blog/Long.md', post('type: blog-post\ntitle: Long\nsummary: s\npublished: 2024-01-01', 'Intro.\n\n## Part two\n\nMore.\n\n```\n## Draft\n```')); + const index = exportNote(vault, 'Projects/Blog/Long.md', new Map()).files.get('index.md')!.toString(); + assert.match(index, /Intro\.\n\n## Part two\n\nMore\./); + assert.ok(!index.includes('private planning')); + }); + + it('strips comments completely and refuses unclosed ones', () => { + assert.equal(stripComments('a b %% y %% c'), 'a b c'); + assert.throws(() => stripComments('text -- secret'), /unclosed comment/); + }); + + it('maps Obsidian callouts and leaves code alone', () => { + const body = convertBody('> [!info] Title\n> text\n\n`[[x]]` and ```\n[[y]] %%z%%\n```', { + liveSlugs: new Map(), images: new Map(), addImage: () => null, warn: () => {}, + }); + assert.match(body, /> \[!NOTE\] Title/); + assert.match(body, /`\[\[x\]\]`/); + assert.match(body, /\[\[y\]\] %%z%%/); + }); + + it('refuses a note that is not ready', () => { + assert.throws(() => exportNote(vault, 'Projects/Blog/Ideas/Cooking/Half Done.md', new Map()), /summary/); + }); + + it('never follows symlinks out of the vault when finding images', () => { + const outside = path.join(root, 'outside'); + mkdirSync(outside); + writeFileSync(path.join(outside, 'secret.png'), 'x'); + symlinkSync(outside, path.join(vault, 'Attachments', 'link')); + symlinkSync(path.join(outside, 'secret.png'), path.join(vault, 'Attachments', 'direct.png')); + const images = indexImages(vault); + assert.equal(images.has('secret.png'), false); + assert.equal(images.has('direct.png'), false); + assert.equal(images.get('timer.png'), path.join(vault, 'Attachments/Garden/timer.png')); + }); +}); + +describe('store', () => { + const paths = () => ({ vault, content }); + + it('lists blog-post notes only', () => { + // Closest to done first: edit, then idea, then notes with no stage + assert.deepEqual(listPosts(paths()).map((p) => p.name), ['Watering on a Timer', 'Half Done', 'Raised Beds']); + }); + + it('keeps note paths inside the blog folder', () => { + assert.equal(safeNotePath(paths(), 'Projects/Blog/Ideas/Gardening/Raised Beds.md'), 'Projects/Blog/Ideas/Gardening/Raised Beds.md'); + assert.equal(safeNotePath(paths(), 'Personal/Finance/Budget.md'), null); + assert.equal(safeNotePath(paths(), 'Projects/Blog/../../Personal/Finance/Budget.md'), null); + assert.equal(safeNotePath(paths(), 'Projects/Blog/missing.md'), null); + }); + + it('pushes, replaces and removes articles without leaving hidden files in articles/', () => { + const a = exportNote(vault, 'Projects/Blog/Ideas/Gardening/Raised Beds.md', new Map()); + pushArticle(paths(), a); + assert.equal(pushedArticles(paths()).get('raised-beds'), a.hash); + pushArticle(paths(), a); + assert.deepEqual(readdirSync(path.join(content, 'articles')), ['raised-beds']); + assert.equal(unpushArticle(paths(), 'raised-beds'), true); + assert.equal(unpushArticle(paths(), 'raised-beds'), false); + assert.throws(() => unpushArticle(paths(), '../vault'), /invalid slug/); + }); + + it('only links to posts that are pushed', () => { + const posts = listPosts(paths()); + assert.equal(linkTargets(posts, new Map()).size, 0); + assert.equal(linkTargets(posts, new Map([['raised-beds', 'h']])).get('Raised Beds'), 'raised-beds'); + }); +}); + +describe('server', () => { + let server: Server; + let base: string; + let built: string[]; + let token: string; + + const start = (authHeader = 'x-authentik-username', users: string[] = [], groups: string[] = []) => + new Promise((resolve) => { + built = []; + const desk = createDesk({ + vault, content, authHeader, users, groups, previewDir: path.join(root, 'preview'), + build: (articles, out) => { + built.push(...readdirSync(articles)); + mkdirSync(path.join(out, 'raised-beds'), { recursive: true }); + writeFileSync(path.join(out, 'raised-beds', 'index.html'), '

Beds

'); + }, + }); + token = desk.token; + server = createServer((req, res) => void desk.handler(req, res)); + server.listen(0, '127.0.0.1', () => { + base = `http://127.0.0.1:${(server.address() as { port: number }).port}`; + resolve(); + }); + }); + + afterEach(() => server?.close()); + + const auth = { 'x-authentik-username': 'owner' }; + const post = (p: string, fields: Record, headers: Record = {}) => + fetch(base + p, { + method: 'POST', + redirect: 'manual', + headers: { ...auth, 'content-type': 'application/x-www-form-urlencoded', origin: base, ...headers }, + body: new URLSearchParams(fields), + }); + + it('requires the SSO header, and an allowed user when set', async () => { + await start('x-authentik-username', ['owner']); + assert.equal((await fetch(base + '/')).status, 403); + assert.equal((await fetch(base + '/', { headers: { 'x-authentik-username': 'someone' } })).status, 403); + assert.equal((await fetch(base + '/', { headers: auth })).status, 200); + assert.equal((await fetch(base + '/healthz')).status, 200); + }); + + it('can allow by authentik group instead of by name', async () => { + await start('x-authentik-username', [], ['authentik Admins']); + const as = (groups: string) => fetch(base + '/', { headers: { ...auth, 'x-authentik-groups': groups } }); + assert.equal((await as('family|authentik Admins')).status, 200); + assert.equal((await as('family|authentik Admins2')).status, 403); + assert.equal((await fetch(base + '/', { headers: auth })).status, 403); + }); + + it('lists posts with what blocks them', async () => { + await start(); + const html = await (await fetch(base + '/', { headers: auth })).text(); + assert.match(html, /Watering on a Timer/); + assert.match(html, /Not ready/); + assert.match(html, /add summary/); + assert.ok(!html.includes('Budget.md')); + }); + + it('refuses posts without the token or from another origin', async () => { + await start(); + const rel = 'Projects/Blog/Ideas/Gardening/Raised Beds.md'; + assert.equal((await post('/publish', { path: rel })).status, 403); + assert.equal((await post('/publish', { path: rel, token }, { origin: 'https://evil.example' })).status, 403); + assert.equal(existsSync(path.join(content, 'articles')), false); + }); + + it('makes a post live and unpublishes it', async () => { + await start(); + const rel = 'Projects/Blog/Ideas/Gardening/Raised Beds.md'; + const res = await post('/publish', { path: rel, token }); + assert.equal(res.status, 303); + assert.ok(existsSync(path.join(content, 'articles', 'raised-beds', 'index.md'))); + assert.equal((await post('/unpublish', { slug: 'raised-beds', token })).status, 303); + assert.equal(existsSync(path.join(content, 'articles', 'raised-beds')), false); + }); + + it('refuses notes outside the blog folder', async () => { + await start(); + assert.equal((await post('/publish', { path: 'Personal/Finance/Budget.md', token })).status, 400); + assert.equal((await post('/preview', { path: '../../etc/passwd.md', token })).status, 400); + }); + + it('previews with the live articles plus the draft, marked as a preview', async () => { + await start(); + mkdirSync(path.join(content, 'articles', 'already-live'), { recursive: true }); + writeFileSync(path.join(content, 'articles', 'already-live', 'index.md'), 'x'); + const res = await post('/preview', { path: 'Projects/Blog/Ideas/Gardening/Raised Beds.md', token }); + assert.equal(res.headers.get('location'), '/blog/raised-beds/'); + assert.deepEqual(built.sort(), ['already-live', 'raised-beds']); + const html = await (await fetch(base + '/blog/raised-beds/', { headers: auth })).text(); + assert.match(html, /Preview, not live/); + assert.equal((await fetch(base + '/blog/..%2f..%2fcontent/articles', { headers: auth })).status, 404); + // Previewing never pushes + assert.equal(existsSync(path.join(content, 'articles', 'raised-beds')), false); + }); +}); diff --git a/blog/desk/export.ts b/blog/desk/export.ts new file mode 100644 index 00000000..10b2c2d7 --- /dev/null +++ b/blog/desk/export.ts @@ -0,0 +1,298 @@ +/** + * Turns ONE vault note into a blog article folder: the push step of the blog desk. + * + * Private side only. The desk runs with the vault mounted read-only; this module reads a + * single note under BLOG_FOLDER and returns the files of its article: + * + * index.md front matter: title, description, published, updated, topics (nothing else) + * body: everything after the note's `## Draft` heading (the last section) + * The public description comes from the note's `summary:`; the note's own + * `description:` is vault metadata (the vault catalog reads it) and stays there. + * images the draft embeds, copied next to index.md + * + * Conversion (code, fenced and inline, is never touched): + * [[Other note|label]] → a link to /blog// when that note is live, else plain text + * ![[image.png|alt]] → ![alt](./image.png), the file copied with the article + * ![[note]] embeds → removed + * [text](note.md) → text + * %% comment %%, → removed (private notes stay private) + * > [!info] Obsidian callouts → the nearest GitHub callout type + * + * Front matter fields such as `related`, `tags` or `source-articles` never leave the + * vault: they would leak note titles. + */ +import { createHash } from 'node:crypto'; +import { lstatSync, readdirSync, readFileSync } from 'node:fs'; +import path from 'node:path'; +import { parse as parseYaml, stringify as stringifyYaml } from 'yaml'; + +export const BLOG_FOLDER = 'Projects/Blog'; +const IMAGE_EXT = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.avif', '.svg']); +const MAX_IMAGE_BYTES = 10 * 1024 * 1024; +const SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/; +/** Paths the blog uses for its own pages (blog/src/lib/posts.ts) */ +export const RESERVED_SLUGS = new Set(['topics', '404', 'rss', 'media', 'assets', '_astro']); + +/** Obsidian callout types → the five GitHub ones the blog styles. */ +const CALLOUTS: Record = { + note: 'NOTE', info: 'NOTE', abstract: 'NOTE', summary: 'NOTE', tldr: 'NOTE', todo: 'NOTE', + question: 'NOTE', help: 'NOTE', faq: 'NOTE', example: 'NOTE', quote: 'NOTE', cite: 'NOTE', + tip: 'TIP', hint: 'TIP', success: 'TIP', check: 'TIP', done: 'TIP', + important: 'IMPORTANT', + warning: 'WARNING', caution: 'CAUTION', attention: 'WARNING', + failure: 'CAUTION', fail: 'CAUTION', missing: 'CAUTION', danger: 'CAUTION', error: 'CAUTION', bug: 'CAUTION', +}; + +export interface ArticleMeta { + title: string; + description: string; + published: string; + updated?: string; + topics: string[]; +} + +export interface NoteInfo { + /** Path relative to the vault, e.g. "Projects/Blog/Ideas/GitOps/Waiting Is Not Failing.md" */ + rel: string; + name: string; + title: string; + slug: string; + stage: string; + pillar: string; + /** Why this note can't be made live yet; empty when it can */ + problems: string[]; +} + +export interface Article { + slug: string; + meta: ArticleMeta; + /** File name → contents, index.md first */ + files: Map; + /** sha256 over the files, to compare with what is already pushed */ + hash: string; + warnings: string[]; +} + +export const slugify = (text: string): string => + text + .normalize('NFKD') + .replace(/[̀-ͯ]/g, '') + .toLowerCase() + .replace(/[^a-z0-9]+/g, '-') + .replace(/^-+|-+$/g, '') + .slice(0, 80) + .replace(/-+$/, ''); + +export const splitFrontmatter = (raw: string): { data: Record; body: string } => { + const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/); + if (!match) return { data: {}, body: raw }; + try { + const data = parseYaml(match[1]); + return { data: data && typeof data === 'object' && !Array.isArray(data) ? data : {}, body: match[2] }; + } catch { + return { data: {}, body: match[2] }; + } +}; + +/** + * Everything after the `## Draft` heading to the end of the note: the post itself. + * `## Draft` is the last section of a blog note, so the post can use its own `##` + * headings. A `## Draft` line inside a code block does not count. + */ +export const draftSection = (body: string): string => { + const lines = body.split(/\r?\n/); + let inFence = false; + for (let i = 0; i < lines.length; i++) { + if (/^\s*(```|~~~)/.test(lines[i])) inFence = !inFence; + if (!inFence && /^##\s+Draft\s*$/.test(lines[i])) return lines.slice(i + 1).join('\n').trim(); + } + return ''; +}; + +const isDate = (v: unknown): boolean => + v instanceof Date ? !Number.isNaN(v.getTime()) : typeof v === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(v); +const toDate = (v: unknown): string => (v instanceof Date ? v.toISOString().slice(0, 10) : String(v)); +const firstHeading = (body: string): string => body.match(/^# (.+)$/m)?.[1]?.trim() ?? ''; + +/** What the desk lists for a note, with everything that blocks making it live. */ +export const describeNote = (rel: string, raw: string): NoteInfo => { + const { data, body } = splitFrontmatter(raw); + const name = path.basename(rel, '.md'); + const title = typeof data.title === 'string' && data.title.trim() ? data.title.trim() : firstHeading(body) || name; + const slug = typeof data.slug === 'string' && data.slug.trim() ? slugify(data.slug) : slugify(title); + const problems: string[] = []; + if (typeof data.summary !== 'string' || !data.summary.trim()) problems.push('add summary: (the public one-line description)'); + if (!isDate(data.published)) problems.push('add published: YYYY-MM-DD'); + if (data.updated !== undefined && data.updated !== null && !isDate(data.updated)) problems.push('updated must be YYYY-MM-DD'); + if (data.topics !== undefined && !Array.isArray(data.topics)) problems.push('topics must be a list'); + if (!draftSection(body)) problems.push('write the post under ## Draft'); + if (!SLUG.test(slug)) problems.push('the title gives no usable slug; set slug:'); + else if (RESERVED_SLUGS.has(slug)) problems.push(`"${slug}" is reserved; set slug:`); + return { + rel, + name, + title, + slug, + stage: typeof data.stage === 'string' ? data.stage : '', + pillar: typeof data.pillar === 'string' ? data.pillar : '', + problems, + }; +}; + +const segments = (text: string): Array<{ code: boolean; text: string }> => { + const out: Array<{ code: boolean; text: string }> = []; + const inline = (t: string) => { + let last = 0; + for (const m of t.matchAll(/(`+)[^`]*?\1/g)) { + out.push({ code: false, text: t.slice(last, m.index) }, { code: true, text: m[0] }); + last = m.index + m[0].length; + } + out.push({ code: false, text: t.slice(last) }); + }; + let last = 0; + for (const m of text.matchAll(/^(```|~~~)[^\n]*\n[\s\S]*?^\1[^\n]*$/gm)) { + inline(text.slice(last, m.index)); + out.push({ code: true, text: m[0] }); + last = m.index + m[0].length; + } + inline(text.slice(last)); + return out; +}; + +const escapeText = (text: string): string => text.replace(/([\\[\]*_<>])/g, '\\$1'); + +export interface ConvertContext { + /** Note name or vault path (without .md) → slug, for notes that are live */ + liveSlugs: Map; + /** Image file name → absolute path, anywhere in the vault */ + images: Map; + /** Collects the images to ship: returns the file name to use next to index.md, or null */ + addImage: (source: string, name: string) => string | null; + warn: (message: string) => void; +} + +/** + * Removes Obsidian (%% %%) and HTML () comments: private asides that must not ship. + * Repeats until nothing changes, so nested or overlapping markers can't leave a comment + * opener behind, then fails closed: an opener that is still there (an unclosed comment) + * stops the export rather than publishing whatever follows it. + */ +export const stripComments = (text: string): string => { + let out = text; + for (let prev = ''; prev !== out; ) { + prev = out; + out = out.replace(/%%[\s\S]*?%%/g, '').replace(//g, ''); + } + if (out.includes('%%') || out.includes(' + + + + + + +
+
+ + + + +
+
+ +
+ +
+ +
+ +
+ + diff --git a/blog/src/lib/posts.ts b/blog/src/lib/posts.ts new file mode 100644 index 00000000..a0ab356d --- /dev/null +++ b/blog/src/lib/posts.ts @@ -0,0 +1,46 @@ +import { getCollection, type CollectionEntry } from 'astro:content'; + +export type Post = CollectionEntry<'posts'>; + +const SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/; +/** Paths the blog itself uses; an article can't take them */ +const RESERVED = new Set(['topics', '404', 'rss', 'media', 'assets', '_astro']); + +/** Published posts, newest first. A folder name that isn't a clean, free slug fails the build. */ +export const getPosts = async (): Promise => { + const posts = await getCollection('posts', ({ data }) => !data.draft); + for (const post of posts) { + if (!SLUG.test(post.id)) { + throw new Error(`Article folder "${post.id}" is not a valid slug (lowercase words joined by hyphens)`); + } + if (RESERVED.has(post.id)) { + throw new Error(`Article folder "${post.id}" uses a name the blog reserves for its own pages`); + } + } + return posts.sort((a, b) => b.data.published.getTime() - a.data.published.getTime()); +}; + +/** Every topic with its posts, alphabetical. */ +export const getTopics = async (): Promise> => { + const topics = new Map(); + for (const post of await getPosts()) { + for (const topic of post.data.topics) { + topics.set(topic, [...(topics.get(topic) ?? []), post]); + } + } + return new Map([...topics.entries()].sort(([a], [b]) => a.localeCompare(b))); +}; + +/** "November 21, 2026", in UTC so the date never shifts with the build machine's zone. */ +export const formatDate = (date: Date): string => + date.toLocaleDateString('en-US', { year: 'numeric', month: 'long', day: 'numeric', timeZone: 'UTC' }); + +/** "2026-11-21" for