WIP: Move back to using mdBook for documantation

mdBook seems somewhat simpler and more lightweight than Docusaurus, so I’m thinking it might just be good to go with it for now! It also has support for [preprocessors](https://rust-lang.github.io/mdBook/for_developers/preprocessors.html) which could be handy if we want to generated some sort of hyperlinked language specification.

.github/workflows/ci.yml

@@ -93,14 +93,33 @@ jobs:
           command: clippy
           args: -- -D warnings
 
-  website:
+  book:
     runs-on: ubuntu-latest
-    name: Build website
+    name: Build and Test Book
+    env:
+      MDBOOK_VERSION: '0.4.2'
+      MDBOOK_LINKCHECK_VERSION: '0.7.0'
     steps:
       - uses: actions/checkout@v2
-      - name: Install website dependencies
+      - name: Install mdBook
+        # Install prebuilt binaries where possible to improve CI performance
+        run: |
+          mkdir -p $HOME/mdbook
+          curl -L https://github.com/rust-lang/mdBook/releases/download/v$MDBOOK_VERSION/mdbook-v$MDBOOK_VERSION-x86_64-unknown-linux-gnu.tar.gz | tar xz -C $HOME/mdbook
+          echo "::add-path::${HOME}/mdbook/"
+          mkdir -p $HOME/mdbook-linkcheck
+          curl -L https://github.com/Michael-F-Bryan/mdbook-linkcheck/releases/download/v$MDBOOK_LINKCHECK_VERSION/mdbook-linkcheck-v$MDBOOK_LINKCHECK_VERSION-x86_64-unknown-linux-gnu.tar.gz | tar xz -C $HOME/mdbook-linkcheck
+          echo "::add-path::${HOME}/mdbook-linkcheck/"
+      - name: Install Javascript dependencies
         run: yarn install
-        working-directory: ./website
-      - name: Build website
+        working-directory: book
+      - name: Build additional Javascript
         run: yarn build
-        working-directory: ./website
+        working-directory: book
+      - name: Build book
+        run: mdbook build
+        working-directory: book
+      - name: Test book
+        run: mdbook test
+        working-directory: book
+      # TODO: Deploy to Github Pages on crate release

CONTRIBUTING.md

@@ -1,3 +1,61 @@
-# Contributing to Pikelet
+# Contributing
 
-A guide to contributing to Pikelet [can be found in the documentation](/website/docs/pikelet/contributing.md).
+## Code of Conduct
+
+Please note that this project is released with a [Code of Conduct](./CODE_OF_CONDUCT.md).
+By participating in this project you agree to abide by its terms.
+
+[code_of_conduct]: https://github.com/pikelet-lang/pikelet/blob/master/CODE_OF_CONDUCT.md
+
+## Matrix room
+
+Joining the matrix room at [#pikelet:matrix.org][pikelet-matrix] is a good way to get in touch with the developers and community.
+
+[pikelet-matrix]: https://app.element.io/#/room/#pikelet:matrix.org
+
+## Prerequisites
+
+We use [Rust][rust] as our implementation language, which can be installed using the [rustup] tool.
+
+For the best experience in working with Rust we also recommend installing IDE support for your editor of choice:
+
+- [Rust Analyzer][rust-analyzer] (for VS Code, Vim Emacs, etc.)
+- [IntelliJ Rust][intellij-rust] (for IntelliJ-based IDEs)
+
+You can learn more about programming in Rust by reading [The Rust Programming Language][rust-book].
+
+[rust]: https://www.rust-lang.org/
+[rustup]: https://rustup.rs/
+[rust-analyzer]: https://rust-analyzer.github.io/
+[intellij-rust]: https://intellij-rust.github.io/
+[rust-book]: https://doc.rust-lang.org/book/
+
+## Workflow
+
+Follow these steps to contribute to the project:
+
+1. Make a fork of the [Pikelet repository][pikelet-repo].
+1. Within your fork, create a branch for your contribution. Use a meaningful name.
+1. Create your contribution, meeting all [contribution quality standards](#quality-standards).
+1. Ensure all the tests pass (`cargo test`).
+1. [Create a pull request][create-a-pr] against the `master` branch of the repository.
+1. Once the pull request is reviewed and CI passes, it will be merged.
+
+[pikelet-repo]: https://github.com/pikelet-lang/pikelet/
+[create-a-pr]: https://help.github.com/articles/creating-a-pull-request-from-a-fork/
+
+## Quality Standards
+
+Most quality and style standards are checked automatically by the CI build.
+Contributions should:
+
+- Separate each **logical change** into its own commit.
+- Include tests for any new functionality in your pull request.
+- Document public functions.
+- Format code with `cargo fmt`.
+- Avoid adding `unsafe` code.
+  If it is necessary, provide an explanatory comment on any `unsafe` block explaining its rationale and why it's safe.
+- Add a descriptive message for each commit. Follow [these commit message guidelines][commit-messages].
+- Document your pull requests. Include the reasoning behind each change, and the testing done.
+
+[commit-messages]: https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html

README.md

@@ -2,7 +2,7 @@
 
 ![Pikelet Mascot][pikelet-mascot]
 
-[pikelet-mascot]: assets/pikelet.png
+[pikelet-mascot]: ./book/assets/pikelet.png
 
 [![Actions Status][actions-badge]][actions-url]
 [![Matrix][matrix-badge]][matrix-lobby]

book/.gitignore

@@ -0,0 +1,6 @@
+# mdBook
+build
+
+# Parcel
+.cache
+dist

book/README.md

@@ -0,0 +1,45 @@
+# Pikelet Book
+
+To build the book, you will first need to [install mdBook][install-mdbook] and [mdbook-linkcheck]:
+
+```sh
+cargo install mdbook mdbook-linkcheck
+```
+
+Note that for consistency we use specific versions of these tools on CI,
+so the one you install might be newer than the one used to build and deploy the book.
+To check the versions we currently assume, look at the [workflows directory](../.github/workflows).
+
+## Building additional JavaScript
+
+In order to highlight the Fathom code examples in the book we override mdBook's built-in [highlight.js] with our own.
+To build the highlighting code, run the following commands using [Yarn]:
+
+```sh
+yarn workspace book install
+yarn workspace book build
+```
+
+You will need to rebuild the book or restart the mdBook server for changes to take effect.
+
+[highlight.js]: https://highlightjs.org/
+[Yarn]: (https://yarnpkg.com/)
+
+## Running the mdBook server
+
+You can then serve the documentation locally by calling the [`serve` command][mdbook-serve]
+from the `book` directory:
+
+```sh
+mdbook serve
+```
+
+Alternatively it can be called from the root of the repository:
+
+```sh
+mdbook serve book
+```
+
+[install-mdbook]: https://rust-lang.github.io/mdBook/cli/index.html#install-cratesio-version
+[mdbook-serve]: https://rust-lang.github.io/mdBook/cli/serve.html
+[mdbook-linkcheck]: https://github.com/Michael-F-Bryan/mdbook-linkcheck#getting-started

book/book.toml

@@ -0,0 +1,36 @@
+[book]
+title = "Pikele Book"
+authors = ["YesLogic Pty. Ltd. <info@yeslogic.com>"]
+description = "Documentation for the Pikelet programming language"
+language = "en"
+multilingual = false
+src = "src"
+
+[build]
+build-dir = "build"
+
+[output.html]
+additional-js = [
+    "dist/index.js",
+]
+
+[output.html.redirect]
+"/installation/index.html" = "./guide/installation.html"
+"/language/index.html" = "./reference.html"
+# "/language/conditionals.html" = TODO
+"/language/functions.html" = "./reference/functions.html"
+"/language/records.html" = "./reference/records.html"
+# "/language/bindings.html" = TODO
+# "/language/type-inference.html" = TODO
+"/language/universes.html" = "./reference/universes.html"
+"/appendix/index.html" = "./specification.html"
+"/appendix/design.html" = "./development/design-goals.html"
+"/appendix/theory.html" = "./specification.html"
+# "/appendix/influences.html" = TODO
+# "/appendix/references.html" = TODO
+
+[output.linkcheck]
+exclude = [
+    '\./contributing\.md', # Bypass `traverse-parent-directories` for this symlink
+    '\./code-of-conduct\.md', # Bypass `traverse-parent-directories` for this symlink
+]

book/index.js

@@ -0,0 +1,49 @@
+import hljs from "highlight.js/lib/core";
+
+hljs.registerLanguage("pikelet", (hljs) => {
+  const KEYWORDS = {
+    keyword: "as fun Fun record Record",
+    built_in: "Type Bool true false U8 U16 U32 U64 S8 S16 S32 S64 F32 F64 String Char Array List",
+  };
+
+  const CHARACTER = {
+    className: "string",
+    begin: /'([^'\\]|\\.)*'/,
+  };
+  const STRING = {
+    className: "string",
+    begin: /"([^"\\]|\\.)*"/,
+  };
+  const NUMBER = {
+    className: "number",
+    begin: /\b[-+]?[0-9][a-zA-Z0-9_\.]*\b/,
+    relevance: 0,
+  };
+
+  const COMMENT = {
+    variants: [
+      hljs.COMMENT("--", "$"),
+      hljs.COMMENT("|||", "$"),
+    ],
+  };
+
+  return {
+    name: "Fathom",
+    keywords: KEYWORDS,
+    contains: [
+      STRING,
+      CHARACTER,
+      NUMBER,
+
+      COMMENT,
+
+      { begin: "->|<-" }, // No markup, relevance booster
+    ],
+  };
+});
+
+window.addEventListener("load", (event) => {
+  document
+    .querySelectorAll("code.language-pikelet")
+    .forEach((block) => hljs.highlightBlock(block));
+});

book/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "book",
+  "version": "0.0.0",
+  "license": "Apache-2.0",
+  "private": true,
+  "author": {
+    "name": "YesLogic Pty. Ltd.",
+    "email": "info@yeslogic.com",
+    "url": "https://yeslogic.com"
+  },
+  "scripts": {
+    "dev": "parcel index.js --no-source-maps",
+    "build": "parcel build index.js --no-source-maps"
+  },
+  "devDependencies": {
+    "parcel-bundler": "^1.12.4"
+  },
+  "dependencies": {
+    "highlight.js": "^10.2.0"
+  }
+}

book/src/SUMMARY.md

@@ -0,0 +1,38 @@
+# Summary
+
+[Pikelet](index.md)
+
+- [Guide](./guide.md)
+  - [Installation](./guide/installation.md)
+  - [Using the REPL](./guide/using-the-repl.md)
+  - [Compiling Standalone Programs]()
+  - [Pikelet as a Configuration Language]()
+  - [Pikelet as a Scripting Language]()
+
+- [Reference](./reference.md)
+  - [Comments](./reference/comments.md)
+  - [Keywords](./reference/keywords.md)
+  - [Names](./reference/names.md)
+  - [Builtins](./reference/builtins.md)
+  - [Literals]()
+  - [Universes](./reference/universes.md)
+  - [Functions](./reference/functions.md)
+  - [Records](./reference/records.md)
+
+- [Specification](./specification.md)
+  - [Core Language]()
+    - [Semantics]()
+    - [Typing]()
+  - [Surface Language]()
+    - [Elaboration]()
+  - [Textual Representation](./specification/textual-representaion.md)
+    - [Lexical Syntax](./specification/textual-representation/lexical-syntax.md)
+    - [Concrete Syntax](./specification/textual-representation/concrete-syntax.md)
+
+- [Development](./development.md)
+  - [Contributing](./development/contributing.md)
+  - [Code of Conduct](./development/code-of-conduct.md)
+  - [Design Goals](./development/design-goals.md)
+  - [Roadmap](./development/roadmap.md)
+
+- [Background Reading](./background.md)

book/src/development.md

@@ -0,0 +1,10 @@
+# Development
+
+Development documentation for contributors to the Pikelet programming language.
+
+## Summary
+
+- [Contributing](./development/contributing.md)
+- [Code of Conduct](./development/code-of-conduct.md)
+- [Design Goals](./development/design-goals.md)
+- [Roadmap](./development/roadmap.md)

book/src/development/code-of-conduct.md

@@ -0,0 +1 @@
+../../../CODE_OF_CONDUCT.md

book/src/development/contributing.md

@@ -0,0 +1 @@
+../../../CONTRIBUTING.md

book/src/development/design-goals.md

@@ -0,0 +1,34 @@
+# Design Goals
+
+- We should aim to empower our users through learnable design and great documentation,
+  rather than by limiting ourselves to what we assume our users already know.
+- Learning Pikelet should be a process of uncovering deeper truths and connections.
+- Pikelet should work well for high level and low level, resource constrained applications.
+- Pikelet should be easy to bootstrap and cross-compile.
+- Languages features should behave predictably, with high quality error messages,
+  as opposed to relying on complicated, hard to understand heuristics.
+- Languages features should simple to implement, with a high power-to-weight ratio.
+- Language features should work in harmony together -
+  it's no use having a linear types if they don't play nicely with
+  dependent types, multistage programming, and effects.
+
+## Research to Watch
+
+There are a number of exciting areas of research that are worth keeping an eye on:
+
+- Dependent types
+- High performance elaboration
+- Effects and Coeffects
+  - Algebraic Effects and Handlers
+  - Effect Runners
+  - Graded Modal Type Theory
+    - Quantitative Type Theory
+    - Multistage Programming
+- Call by Push Value
+- Codata vs. Data
+- Modular Programming with Dependent Records
+- Datatype Generic Programming
+  - Levitated data descriptions
+  - Data Layout Interpretations
+  - Ornamented Data Types
+- Projectional Editors

website/docs/pikelet/roadmap.md → book/src/development/roadmap.md

@@ -1,17 +1,10 @@
----
-id: roadmap
-title: Roadmap
-sidebar_label: Roadmap
-keywords:
-  - docs
-  - pikelet
----
-
-Our main aim is to start off with a simple configuration language, like
-[Dhall][dhall]. From there we will progressively add features to gain more
-flexibility. We want to provide a textual syntax up-front, but we should aim to
-keep the core language reasonably decoupled from this, allowing us to provide
-support for [projectional editing][structure-editor-wikipedia] in the future.
+# Roadmap
+
+Our main aim is to start off with a simple configuration language, like [Dhall][dhall].
+From there we will progressively add features to gain more flexibility.
+We want to provide a textual syntax up-front,
+but we should aim to keep the core language reasonably decoupled from this,
+allowing us to provide support for [projectional editing][structure-editor-wikipedia] in the future.
 
 [dhall]: https://dhall-lang.org/
 [structure-editor-wikipedia]: https://en.wikipedia.org/wiki/Structure_editor