docs: use Zola for static docs

https://www.getzola.org/

For local development use: `just docs`

.github/workflows/ci.yml

@@ -139,6 +139,15 @@ jobs:
         run: just init-db
       - name: Rebuild All
         run: just build-all
+  docs:
+    name: Build Docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: true
+      - uses: cashapp/activate-hermit@v1
+      - run: just docs
   integration-shard:
     name: Shard Integration Tests
     runs-on: ubuntu-latest

.github/workflows/docs.yml

@@ -0,0 +1,22 @@
+on:
+  push:
+    branches:
+      - main
+name: Publish Docs
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main'
+    steps:
+      - name: checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: true
+      - name: build_and_deploy
+        uses: shalzz/[email protected]
+        env:
+          # Target branch
+          PAGES_BRANCH: gh-pages
+          # Or if publishing to the same repo, use the automatic token
+          TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          BUILD_DIR: docs

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "docs/themes/adidoks"]
+	path = docs/themes/adidoks
+	url = https://github.com/aaranxu/adidoks.git

Justfile

@@ -135,3 +135,8 @@ lint-frontend: build-frontend
 # Lint the backend
 lint-backend:
   @golangci-lint run ./...
+
+# Run live docs server
+docs:
+  git submodule update --init --recursive
+  cd docs && zola serve

bin/.zola-0.18.0.pkg

@@ -0,0 +1 @@
+hermit

bin/zola

@@ -0,0 +1 @@
+.zola-0.18.0.pkg

docs/config.toml

@@ -0,0 +1,143 @@
+# The URL the site will be built for
+base_url = "https://tbd54566975.github.io/ftl/"
+title = "FTL"
+description = "FTL - Towards a 𝝺-calculus for large-scale systems"
+
+# The site theme to use.
+theme = "adidoks"
+
+# The default language; used in feeds and search index
+# Note: the search index doesn't support Chinese/Japanese/Korean Languages
+default_language = "en"
+
+# Whether to automatically compile all Sass files in the sass directory
+compile_sass = true
+
+# Whether to generate a feed file for the site
+generate_feed = true
+
+# When set to "true", the generated HTML files are minified.
+minify_html = false
+
+# The taxonomies to be rendered for the site and their configuration.
+taxonomies = [
+  { name = "authors" }, # Basic definition: no feed or pagination
+]
+
+# Whether to build a search index to be used later on by a JavaScript library
+# When set to "true", a search index is built from the pages and section
+# content for `default_language`.
+build_search_index = true
+
+[search]
+# Whether to include the title of the page/section in the index
+include_title = true
+# Whether to include the description of the page/section in the index
+include_description = true
+# Whether to include the rendered content of the page/section in the index
+include_content = true
+
+[markdown]
+# Whether to do syntax highlighting.
+# Theme can be customised by setting the `highlight_theme`
+# variable to a theme supported by Zola
+highlight_code = true
+
+[extra]
+# Put all your custom variables here
+author = "The FTL Team"
+github = "https://github.com/TBD54566975/ftl"
+twitter = "https://twitter.com/TBD54566975"
+email = "[email protected]"
+
+# If running on netlify.app site, set to true
+is_netlify = false
+
+# Set HTML file language
+language_code = "en-US"
+
+# Set theme-color meta tag for Chrome browser
+theme_color = "#fff"
+
+# More about site's title
+title_separator = "|"                         # set as |, -, _, etc
+title_addition = "Modern Documentation Theme"
+
+
+# Set date format in blog publish metadata
+timeformat = "%B %e, %Y"   # e.g. June 14, 2021
+timezone = "Australia/NSW"
+
+# Edit page on reposity or not
+edit_page = true
+docs_repo = "https://github.com/TBD54566975/ftl"
+repo_branch = "main"
+
+## Math settings
+# options: true, false. Enable math support globally,
+# default: false. You can always enable math on a per page.
+math = false
+library = "katex" # options: "katex", "mathjax". default is "katex".
+
+## Open Graph + Twitter Cards
+[extra.open]
+enable = true
+# this image will be used as fallback if a page has no image of its own
+image = "doks.png"
+twitter_site = "TBD54566975"
+twitter_creator = "TBD54566975"
+facebook_author = ""
+facebook_publisher = ""
+og_locale = "en_US"
+
+## JSON-LD
+[extra.schema]
+type = "Organization"
+logo = "logo-doks.png"
+twitter = "https://twitter.com/TBD54566975"
+linked_in = ""
+github = "https://github.com/TBD54566975"
+section = "blog"                            # see config.extra.main~url
+## Sitelinks Search Box
+site_links_search_box = false
+
+
+# Menu items
+[[extra.menu.main]]
+name = "Docs"
+section = "docs"
+url = "/docs/getting-started/introduction/"
+weight = 10
+
+[[extra.menu.main]]
+name = "Blog"
+section = "blog"
+url = "/blog/"
+weight = 20
+
+[[extra.menu.social]]
+name = "Twitter"
+pre = '<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-twitter"><path d="M23 3a10.9 10.9 0 0 1-3.14 1.53 4.48 4.48 0 0 0-7.86 3v1A10.66 10.66 0 0 1 3 4s-4 9 5 13a11.64 11.64 0 0 1-7 2c9 5 20 0 20-11.5a4.5 4.5 0 0 0-.08-.83A7.72 7.72 0 0 0 23 3z"></path></svg>'
+url = "https://twitter.com/TBD54566975"
+weight = 10
+
+[[extra.menu.social]]
+name = "GitHub"
+pre = '<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-github"><path d="M9 19c-5 1.5-5-2.5-7-3m14 6v-3.87a3.37 3.37 0 0 0-.94-2.61c3.14-.35 6.44-1.54 6.44-7A5.44 5.44 0 0 0 20 4.77 5.07 5.07 0 0 0 19.91 1S18.73.65 16 2.48a13.38 13.38 0 0 0-7 0C6.27.65 5.09 1 5.09 1A5.07 5.07 0 0 0 5 4.77a5.44 5.44 0 0 0-1.5 3.78c0 5.42 3.3 6.61 6.44 7A3.37 3.37 0 0 0 9 18.13V22"></path></svg>'
+url = "https://github.com/TBD54566975/ftl"
+post = "v0.1.0"
+weight = 20
+
+# Footer contents
+[extra.footer]
+info = 'Powered by <a href="https://www.getzola.org/">Zola</a>, and <a href="https://github.com/aaranxu/adidoks">AdiDoks</a>'
+
+[[extra.footer.nav]]
+name = "Privacy"
+url = "/privacy-policy/"
+weight = 10
+
+[[extra.footer.nav]]
+name = "Code of Conduct"
+url = "/docs/contributing/code-of-conduct/"
+weight = 20

docs/content/_index.fi.md

@@ -0,0 +1,51 @@
++++
+title = "Nykyaikainen teema dokumentaatiolle"
+
+
+# The homepage contents
+[extra]
+lead = '<b>AdiDoks</b> on nykyaikainen teema dokumentaatiosivustoille. Se on portattu Zolalle Hugo-teemasta nimeltä <a href="https://github.com/h-enk/">Doks</a>.'
+url = "/docs/getting-started/introduction/"
+url_button = "Aloita"
+repo_version = "GitHub v0.1.0"
+repo_license = "Open-source MIT License."
+repo_url = "https://github.com/aaranxu/adidoks"
+
+# Menu items
+[[extra.menu.main]]
+name = "Dokumentaatio"
+section = "docs"
+url = "/docs/getting-started/introduction/"
+weight = 10
+
+[[extra.menu.main]]
+name = "Blogi"
+section = "blog"
+url = "/blog/"
+weight = 20
+
+[[extra.list]]
+title = "Turvallisuustietoinen"
+content = 'Saat A+-arvosanoja <a href="https://observatory.mozilla.org/analyze/adidoks.org">Mozilla Observatoryssä</a> suoraan. Voit vaihtaa turvallisuusheadereita tarpeidesi mukaan.'
+
+[[extra.list]]
+title = "Salamannopea ⚡️"
+content = 'Saat hyvät pisteet <a href="https://googlechrome.github.io/lighthouse/viewer/?gist=7731347bb8ce999eff7428a8e763b637">Google Lighthousessa</a> defaultina. Doks poistaa tarpeettomat css:t, esinoutaa linkit, ja lataa kuvat laiskasti.'
+
+[[extra.list]]
+title = "SEO-valmis"
+content = "Käytä järkeviä oletusarvoja rakenteiselle datalle, open graphille ja Twitter-korteille. Tai muunna SEO-asetukset mieleisiksesi helposti."
+
+[[extra.list]]
+title = "Fulltext-haku"
+content = "Tee hakuja sivuillesi FlexSearchilla. Muuntele indeksointiasetuksia mieleisiksesi helposti."
+
+[[extra.list]]
+title = "Sivujen layoutit"
+content = "Rakenna sivuja laskeutumisivun, blogisivun tai dokumentaatiolayoutin mukaan. Lisää osioita ja komponentteja tarpeen mukaan."
+
+[[extra.list]]
+title = "Dark mode"
+content = "Vaihda hämärässä käytettävään käyttöliittymäteemaan nappia painamalla. Muuta värit muuttujilla vastaamaan brändiäsi."
+
++++

docs/content/_index.md

@@ -0,0 +1,51 @@
++++
+title = "Modern Documentation Theme"
+
+
+# The homepage contents
+[extra]
+lead = '<b>AdiDoks</b> is a modern documentation theme, which is a port of the Hugo theme <a href="https://github.com/h-enk/">Doks</a> for Zola.'
+url = "/docs/getting-started/introduction/"
+url_button = "Get started"
+repo_version = "GitHub v0.1.0"
+repo_license = "Open-source MIT License."
+repo_url = "https://github.com/aaranxu/adidoks"
+
+# Menu items
+[[extra.menu.main]]
+name = "Docs"
+section = "docs"
+url = "/docs/getting-started/introduction/"
+weight = 10
+
+[[extra.menu.main]]
+name = "Blog"
+section = "blog"
+url = "/blog/"
+weight = 20
+
+[[extra.list]]
+title = "Security aware"
+content = 'Get A+ scores on <a href="https://observatory.mozilla.org/analyze/adidoks.org">Mozilla Observatory</a> out of the box. Easily change the default Security Headers to suit your needs.'
+
+[[extra.list]]
+title = "Fast by default ⚡️"
+content = 'Get 100 scores on <a href="https://googlechrome.github.io/lighthouse/viewer/?gist=7731347bb8ce999eff7428a8e763b637">Google Lighthouse</a> by default. Doks removes unused css, prefetches links, and lazy loads images.'
+
+[[extra.list]]
+title = "SEO-ready"
+content = "Use sensible defaults for structured data, open graph, and Twitter cards. Or easily change the SEO settings to your liking."
+
+[[extra.list]]
+title = "Full text search"
+content = "Search your Doks site with FlexSearch. Easily customize index settings and search options to your liking."
+
+[[extra.list]]
+title = "Page layouts"
+content = "Build pages with a landing page, blog, or documentation layout. Add custom sections and components to suit your needs."
+
+[[extra.list]]
+title = "Dark mode"
+content = "Switch to a low-light UI with the click of a button. Change colors with variables to match your branding."
+
++++

docs/content/authors/_index.md

@@ -0,0 +1,18 @@
++++
+title = "Authors"
+description = "The authurs of the blog articles."
+date = 2021-04-01T08:00:00+00:00
+updated = 2021-04-01T08:00:00+00:00
+draft = false
+
+# If add a new author page in this section, please add a new item,
+# and the format is as follows:
+#
+# "author-name-in-url" = "the-full-path-of-the-author-page"
+#
+# Note: We use quoted keys here.
+[extra.author_pages]
+"aaran-xu" = "authors/aaran-xu.md"
++++
+
+The authors of the blog articles.

docs/content/authors/aaran-xu.md

@@ -0,0 +1,11 @@
++++
+title = "Aaran Xu"
+description = "Creator of AdiDoks."
+date = 2021-04-01T08:50:45+00:00
+updated = 2021-04-01T08:50:45+00:00
+draft = false
++++
+
+Creator of **AdiDoks**.
+
+[@aaranxu](https://github.com/aaranxu)

docs/content/blog/_index.md

@@ -0,0 +1,7 @@
++++
+title = "Blog"
+description = "Blog"
+sort_by = "date"
+paginate_by = 2
+template = "blog/section.html"
++++

docs/content/blog/hello-world.md

@@ -0,0 +1,41 @@
++++
+title = "Hello World"
+description = "Introducing Doks, a Hugo theme helping you build modern documentation websites that are secure, fast, and SEO-ready — by default."
+date = 2021-05-01T09:19:42+00:00
+updated = 2021-05-01T09:19:42+00:00
+draft = false
+template = "blog/page.html"
+
+[taxonomies]
+authors = ["Rustaceans"]
+
+[extra]
+lead = "This is the source code of the traditional <b>Hello World</b> program."
++++
+
+```rust
+// This is a comment, and is ignored by the compiler
+
+// This is the main function
+fn main() {
+    // Statements here are executed when the compiled binary is called
+
+    // Print text to the console
+    println!("Hello World!");
+}
+```
+
+`println!` is a macro that prints text to the console.
+
+A binary can be generated using the Rust compiler: `rustc`.
+
+```bash
+$ rustc hello.rs
+```
+
+`rustc` will produce a `hello` binary that can be executed.
+
+```bash
+$ ./hello
+Hello World!
+```