Development

Setting Up

Before you can work on the site, you'll need the following:

• A copy of Git, and a GitHub account set up with an SSH key.

• A fork of the site's GitHub repository.

• A code editor that can provide an adequate editing experience for Svelte projects. We recommend:

  • Visual Studio Code, which we include recommended extensions for.
  • IntelliJ IDEA Ultimate, which we include run configurations for.

  If you feel we could improve the editing experience in your favourite editor by providing configuration files in this repository, please feel free to contact us or submit a Pull Request.

• NodeJS, version 20.0.0 or later.

• Corepack enabled for pnpm (run the corepack enable command in a terminal).

Once you've finished setting up the project requirements, please ensure the following:

1. The project's dependencies are installed, using pnpm install.
2. You're able to build a copy of the site, using pnpm build.
3. The development server starts correctly, using pnpm dev.

Documentation

Be sure to also read the following articles:

• Contribution Guidelines
• Submitting Work
• Project Layout
• Tooling
• Configuration

Development Notes

When working on the project, you should be aware of the following:

• The development server can be slow, especially if you've just started it. The production build will be considerably faster regardless, so try not to focus too much on this.

• If things aren't rendering how you expect, the development server may still be optimising dependencies. This can take a while, and you may need to refresh the page a few times before it finishes.

• While we do use TypeScript everywhere, it still exists on top of JavaScript, a weakly typed language. This means that, occasionally, you'll run into issues with the type system. Try your best to solve any typing issues that crop up, but remember that it isn't a requirement to get the site building.

• The markdown-layout.svelte file is special, and a little broken. mdsvex, which handles components and pages written in Markdown, doesn't support TypeScript. This means that you'll run into errors if you try to use type hints or import type in the markdown-layout.svelte file, and you can do little about it other than suppressing the errors.

• When writing Remark and Rehype plugins, you should be aware of the following:

  • It is best to use a Remark plugin when you want to work with the AST used to translate Markdown to HTML.

  • It is best to use a Rehype plugin when you want to work with the HTML that was generated using the Markdown.

  • If you want to modify the AST, you'll need to iterate over and modify the tree passed to your plugin's function, instead of using the visit function from unist-util-visit. However, the visit function is useful for filtering over the tree if you don't need to modify it.

    A good example of a simple plugin that modifies the tree is the rehype-color-chips plugin.

• During development, the search index will quickly become out-of-date. To fix this, follow these steps:

  1. Stop the development server if it is running.
  2. Delete the build/ folder.
  3. Delete the static/pagefind folder.
  4. Rebuild your local copy of the site using pnpm build.
  5. Start the development server again.