I’ve made a few little additions to this site, the biggest one being a new page at /making which shows some of my side-projects. It’s driven by a new projects content collection whose schema looks like this:

const projects = defineCollection({
  loader: glob({ pattern: '**/[^_]*.{md,mdx}', base: './src/content/projects' }),
  schema: ({ image }) =>
    z.object({
      title: z.string(),
      byline: z.string().describe('One-sentence description of what it is'),
      stage: z
        .enum(['active-development', 'actively-maintained', 'finished', 'paused', 'archived'])
        .describe('Lifecycle: am I still working on this?'),
      audience: z
        .enum(['public', 'public-with-dragons', 'personal-only'])
        .describe("Who's it for, can others use it?"),
      kind: z.enum(['proper', 'toy', 'experiment']).optional().describe('How seriously to take it'),
      icon: image().optional().describe('Square icon'),
      image: image().optional().describe('Main graphic'),
      website: z.url().optional(),
      github: z.url().optional(),
      featured: z.boolean().default(false),
      startDate: z.coerce.date().optional(),
      draft: z.boolean().default(false),
    }),
});

The /making page uses a new ProjectCard component which looks like this:

The component also has a compact variant which only shows the icon, title and byline. I’m not using this anywhere right now but will probably end up using it to show featured or current projects on the homepage.

I decided against creating individual pages for each project because it doesn’t feel like they have enough information to warrant it, but I may revisit this in the future.

Support for article series

I occasionally write articles as a series and wanted an easy way to show that in articles, so I’ve added a series field to the articles schema which references a new JSON-based series content collection.

[
  {
    "id": "loomclone",
    "name": "LoomClone",
    "intro": "A short series on how and why I built my own video recording and hosting platform to replace tools like Loom."
  },
  {
    "id": "website-redesign",
    "name": "Website Redesign",
    "intro": "A series documenting the design and development of this website."
  }
]

Now, adding series: website-redesign to an article’s frontmatter will automatically show a callout at the top of every article in that series like this…

It’s only rendered if a series has more than one non-draft article and the links are shown in ascending order of pubDate, with the current article being bold.

A few other bits

I’ve made a few other little tweaks too…

Skip to content link

Pressing Tab on any page shows and focusses a “Skip to content” link pointing to the main content. This is helpful for folks who use keyboard navigation. The SkipLink.astro component is included at the top of MainNavigation.astro which is loaded on every page.

<a href="#main" class="skip-link">Skip to content</a>

<style>
  .skip-link {
    position: fixed;
    top: var(--space-s);
    left: var(--space-s);
    z-index: 1001;
    /* ... */

    transform: translateY(calc(-100% - var(--space-s)));

    &:focus {
      transform: translateY(0);
    }
  }
</style>

Back-to-top links

Articles, notes and content pages now include a link at the end which scrolls you back up to the top of the page.

<a href="#top" class="back-to-top">Back to top <span aria-hidden="true">↑</span></a>

Under the hood

I did a bit of tidying up in the codebase – mostly simplifying or removing config files, but I also converted my check-content Claude command into an Agent Skill and simplified some of the developer docs.

AI coding agents aften want to use the timeout command which isn’t available on macOS. This is a nice little standalone implementation in Haskell.

When I released Astro Editor in January, the website was a hastily vibe-coded single HTML file full of the purple gradients that LLMs love so much. I’ve been meaning to re-do it for ages while knowing that a proper job would necessarily involve adding some actual documentation for the app too.

Because while Astro Editor isn’t an especially complicated app, its minimalist nature means that a lot of its features are hidden behind keyboard shortcuts and command palettes and so on. Moreover, users with unusual Astro setups deserve to have a decent reference for how schemas are read and how overrides are applied and used.

I finally found the time to do this last week, so https://astroeditor.danny.is is now a much better-looking Starlight site with a custom index page.

The homepage is simpler and responds properly to light and dark mode switches, and more importantly I think I’ve done a much better job of demonstrating what the app is and the features that make it unique and useful.

The new documentation site

By far the biggest piece of work was writing the documentation pages because there were three or four options for how to conceptually structure them which all had their own pros and cons. In the end I settled on this top-level structure.

1. Getting Started. The obligatory Quick Start and Installation pages, plus a dedicated Philosophy page covering writer mode vs coder mode and the app’s core principles. Arguably the most important page in here is Introduction to Astro Editor, which is an attempt to explain, using examples, why AE exists and the fundamentals of how it works.
2. The Editor. Groups all the features for actually using the editor to write and puts them before any mention of file management or frontmatter fields, because this stuff is a bit less obvious from simply using the app.
3. File Management. Groups everything to do with the left sidebar. Right now that’s mostly self-explanatory.
4. Frontmatter & Schemas. Everything to do with schemas and the right sidebar, hopefully explained clearly and at the right level.
5. Preferences. A single page explaining all the preference panes and settings.
6. Reference. These aren’t really meant to be read top-to-bottom, they’re for looking stuff up.
   • Keyboard shortcuts
   • Commands
   • Overrides
   • URL Scheme
   • Advanced Stuff
   • How YAML is Handled
7. Releases. A list of all releases with their release notes.

Using AI to write docs

While I used Claude Code extensively to build the homepage, set up Starlight and constantly move, combine and rename pages as I changed my mind, it didn’t write many words or decide how to organise things. I tried that with the (much larger) docs for taskdn and while they’re mostly correct, they are not fun to read. So my use of AI with these docs was mostly limited to “Check I’m not missing anything here” or “Fix any typos”.

The major exception here is the documents under reference. An agentic coding tool with access to the actual codebase is perfectly suited to writing and maintaining dry, technical docs like a canonical keyboard shortcut or commands reference.

I think AI agents are awesome when used right. But I’m also fed up to the back teeth with reading AI slop, and used right for documentation is very different to used right for coding.

This note was created and published from the share sheet on my phone, using the app I discuss in this article!

Interesting discussion about bookmarks. I’d love to see a sensible standard for this emerge.