V2

.gitignore

@@ -1,3 +1,21 @@
-*~
-_build
+# build output
+dist/
+# generated types
+.astro/
+
+# dependencies
+node_modules/
+
+# logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+
+# environment variables
+.env
+.env.production
+
+# macOS-specific files
 .DS_Store

README.md

@@ -0,0 +1,47 @@
+# Capabilities for coders
+
+[![Built with Starlight](https://astro.badg.es/v2/built-with-starlight/tiny.svg)](https://starlight.astro.build)
+
+This is the repository for Capabilities for coders;
+
+This project is build with [starlight](https://starlight.astro.build/), which is an extension for [astro](https://astro.build/).
+
+---
+
+# Building and deploying
+
+### Prerequisites:
+
+To build this site you will need:
+
+1. an installation of nodejs (version 18, 20 or later). I recommend using [NVM](https://github.com/nvm-sh/nvm) to set this up.
+2. a JS package manager. This project has been written with [pnpm](https://pnpm.io/installation).
+
+To deploy it, you will need to configure a web server such as apache or nginx to serve the static build files. By default, these will all be generated in `./build/`
+
+### Installing capabilities for coders
+
+Astro is a static site generator; It generates static files which can be served with any regular web server. To build this project:
+
+1. clone the repo
+2. install the dependencies
+3. build the site
+
+```sh
+git clone https://github.com/jeremysinger/capabilitiesforcoders.git
+cd capabilities-for-coders-v2
+pnpm install
+pnpm build
+```
+
+---
+
+## Project Structure
+
+Broadly, this site covers CHERI, Morello, and CHERI-BSD. We also have a separate category for common compilers warnings or errors. A folder for each of these can be found in `src/content/docs`; each markdown file will automatically be converted into a corresponding webpage.
+
+In order to get the page to appear on the sidebar for site navigation, you also need to modify the sidebar configuration in `astro.config.mjs`. This should be fairly self explanatory, but check the starlight docs if you need clarification.
+
+Images can be added to `src/assets/` and embedded in Markdown with a relative link.
+
+Static assets, like favicons, can be placed in the `public/` directory.

astro.config.mjs

@@ -0,0 +1,91 @@
+import { defineConfig } from "astro/config";
+import starlight from "@astrojs/starlight";
+import starlightLinksValidator from "starlight-links-validator";
+import rehypeMermaid from "rehype-mermaid";
+
+// https://astro.build/config
+export default defineConfig({
+  markdown: {
+    rehypePlugins: [[rehypeMermaid, { strategy: "pre-mermaid", dark: true }]],
+  },
+  site: "https://capabilitiesforcoders.com",
+  integrations: [
+    starlight({
+      head: [
+        {
+          tag: "script",
+          attrs: { type: "module" },
+          content:
+            "import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs'; mermaid.initialize({ startOnLoad: true });",
+        },
+      ],
+      title: "Capabilities for Coders",
+      logo: { src: "./src/assets/cherry_bakewell.png" },
+      favicon: "/favicon-32x32.png",
+      social: {
+        github: "https://github.com/JakeTrevor/capabilities-for-coders-v2",
+      },
+      editLink: {
+        baseUrl:
+          "https://github.com/JakeTrevor/capabilities-for-coders-v2/edit/main",
+      },
+      plugins: [starlightLinksValidator()],
+      sidebar: [
+        {
+          label: "Cheri",
+          items: [
+            "cheri/what-is-cheri",
+            "cheri/capabilities",
+            {
+              collapsed: true,
+              label: "Compiling for CHERI",
+              items: [
+                "cheri/compiling/cross-compiling",
+                "cheri/compiling/purecap",
+                "cheri/compiling/hybrid",
+              ],
+            },
+            "cheri/running",
+            "cheri/header",
+            "cheri/purecap-and-hybrid",
+            "cheri/printf",
+            "cheri/purposes_of_sealed_capabilities",
+            "cheri/how_to_seal",
+            "cheri/setbounds",
+            "cheri/tagcheck",
+          ],
+        },
+        {
+          label: "Morello",
+          items: [
+            "morello/get-a-board",
+            "morello/how_to_tell_morello",
+            "morello/teardown",
+            "morello/python",
+            "morello/compartmentalisation",
+            "morello/benchmark_abi",
+          ],
+        },
+        {
+          label: "CheriBSD",
+          items: [
+            "cheri-bsd/installing_gdb",
+            "cheri-bsd/compile_on_freebsd",
+            "cheri-bsd/configure_networking",
+            "cheri-bsd/hardware_performance_counters",
+            "cheri-bsd/ldpreload",
+            "cheri-bsd/shared_library_path",
+          ],
+        },
+        {
+          label: "Warnings and Errors",
+          items: [
+            "warnings-and-errors/capability_misuse",
+            "warnings-and-errors/implicit_conversion",
+            "warnings-and-errors/unclear_provenance",
+          ],
+        },
+      ],
+    }),
+  ],
+});