feat(site): Substantial site redesign

This redesign is still a draft with pieces unfinished, but it's at the point where we can probably start to have others contribute to it. Signed-off-by: Andrew Lilley Brinker <[email protected]>
mitre · Nov 1, 2024 · 7155d6e · 7155d6e
1 parent 56dd7a7
commit 7155d6e
Show file tree

Hide file tree

Showing 117 changed files with 2,897 additions and 1,409 deletions.
diff --git a/.zed/settings.json b/.zed/settings.json
@@ -0,0 +1,35 @@
+// Folder-specific settings
+//
+// For a full list of overridable settings, and general information on folder-specific settings,
+// see the documentation: https://zed.dev/docs/configuring-zed#settings-files
+{
+  "lsp": {
+    "deno": {
+      "settings": {
+        "deno": {
+          "enable": true
+        }
+      }
+    }
+  },
+  "languages": {
+    "TypeScript": {
+      "language_servers": [
+        "deno",
+        "!typescript-language-server",
+        "!vtsls",
+        "!eslint"
+      ],
+      "formatter": "language_server"
+    },
+    "TSX": {
+      "language_servers": [
+        "deno",
+        "!typescript-language-server",
+        "!vtsls",
+        "!eslint"
+      ],
+      "formatter": "language_server"
+    }
+  }
+}
diff --git a/site/config.toml b/site/config.toml
@@ -4,53 +4,54 @@ base_url = "https://mitre.github.io/hipcheck"
 # Don't use Sass
 compile_sass = false
 
-# Build the search engine.
+# Build the search index.
 build_search_index = true
 
+[search]
+
+# Use the elasticlunr format for the search index.
+index_format = "elasticlunr_javascript"
+
 [markdown]
 
 # Use syntax highlighting.
 highlight_code = true
+highlight_theme = "ayu-light"
 
 [extra]
 
 # Define the site navigation.
 nav = [
-    { name = "Documentation", url = "@/docs/_index.md" },
-    { name = "Contribute", url = "@/contribute/_index.md" },
-    # TODO: Uncomment this when the blog is ready.
-    # { name = "Blog", url = "@/blog/_index.md" },
-    { sep = true },
+    { name = "Docs", url = "@/docs/_index.md" },
+    { name = "Contribute", url = "@/docs/contributing/_index.md" },
+    { name = "Blog", url = "@/blog/_index.md" },
     { name = "Get Help", url = "https://github.com/mitre/hipcheck/discussions", icon = "life-buoy", external = true },
-    { name = "Install", url = "@/install/_index.md", highlight = true, icon = "arrow-down" },
-    { sep = true },
+    { name = "Install", url = "@/docs/getting-started/install.md", highlight = true, icon = "arrow-down" },
     { url = "https://github.com/mitre/hipcheck", icon = "github", icononly = true },
-    { url = "#", icon = "sun", icononly = true, id = "toggle-darkmode" },
 ]
 
 # Define the site footer.
 footer = [
     [
         { name = "Documentation", title = true },
-        { name = "Quickstart", url = "@/docs/quickstart/_index.md" },
+        { name = "Getting Started", url = "@/docs/getting-started/_index.md" },
         { name = "Complete Guide", url = "@/docs/guide/_index.md" },
-        { name = "Requests for Discussion", url = "@/rfds/_index.md" },
-        # TODO: Uncomment this when the blog is ready.
-        # { name = "Development Blog", url = "@/blog/_index.md" },
+        { name = "Requests for Discussion", url = "@/docs/rfds/_index.md" },
+        { name = "Blog", url = "@/blog/_index.md" },
         { name = "Project", title = true },
-        { name = "Hipcheck Values", url = "@/rfds/0002-hipchecks-values.md" },
+        { name = "Hipcheck Values", url = "@/docs/rfds/0002-hipchecks-values.md" },
         { name = "Open Source License", url = "https://github.com/mitre/hipcheck/blob/main/LICENSE", external = true },
         { name = "Code of Conduct", url = "https://github.com/mitre/hipcheck/blob/main/CODE_OF_CONDUCT.md", external = true },
     ],
     [
         { name = "Install", title = true },
-        { name = "Installer", url = "@/install/_index.md" },
+        { name = "Installer", url = "@/docs/getting-started/install.md" },
         { name = "Container Image", url = "https://hub.docker.com/r/mitre/hipcheck", external = true },
         { name = "Release Notes", url = "https://github.com/mitre/hipcheck/releases", external = true },
         { name = "Changelog", url = "https://github.com/mitre/hipcheck/blob/main/CHANGELOG.md", external = true },
         { name = "Packages", title = true },
-        { name = "GitHub", url = "https://github.com/mitre/hipcheck", external = true },
-        { name = "Crates.io", url = "https://crates.io/crates/hipcheck", external = true },
+        { name = "Hipcheck", url = "https://github.com/mitre/hipcheck/releases/tag/hipcheck-v3.7.0", external = true },
+        { name = "Rust Plugin SDK", url = "https://crates.io/crates/hipcheck-sdk", external = true },
     ],
     [
         { name = "Contribute", title = true },

diff --git a/site/content/contribute/_index.md b/site/content/contribute/_index.md
diff --git a/site/content/docs/_index.md b/site/content/docs/_index.md
@@ -1,31 +1,30 @@
 ---
 title: Documentation
+template: docs.html
+page_template: docs_page.html
 sort_by: weight
 ---
 
 # Documentation
 
 Welcome to the official Hipcheck documentation!
 
-## Quickstart
+<div class="grid grid-cols-2 gap-8 mt-8">
 
-This is a guide to installing and running Hipcheck for the first time, and
-is our recommended starting point for beginners!
+{% waypoint(title="Getting Started", path="@/docs/getting-started/_index.md", icon="map-pin") %}
+A guide to installing and running Hipcheck for the first time.
+{% end %}
 
-{{ button(link="@/docs/quickstart/_index.md", text="Check out the Quickstart Guide") }}
+{% waypoint(title="Complete Guide", path="@/docs/guide/_index.md", icon="map") %}
+A complete guide to all of Hipcheck's functionality.
+{% end %}
 
-## Complete Guide
+{% waypoint(title="Contribute", path="@/docs/contributing/_index.md", icon="award") %}
+Learn how to make contributions to Hipcheck itself.
+{% end %}
 
-This is a complete guide to all of Hipcheck's functionality, including both
-how to use Hipcheck and how to develop plugins for Hipcheck.
+{% waypoint(title="RFDs", path="@/docs/rfds/_index.md", icon="pen-tool") %}
+Design documents proposing important changes to Hipcheck.
+{% end %}
 
-{{ button(link="@/docs/guide/_index.md", text="Check out the Complete Guide") }}
-
-## RFDs
-
-Hipcheck's evolution is managed by Requests for Discussion (RFDs), documents
-which describe in detail any proposals for improvement or modification of
-Hipcheck's behavior. This list shows all completed RFDs; draft or proposed
-RFDs can be found on the [Hipcheck GitHub repository](https://github.com/mitre/hipcheck).
-
-{{ button(link="@/rfds/_index.md", text="Check out the RFDs") }}
+</div>
diff --git a/site/content/docs/contributing/_index.md b/site/content/docs/contributing/_index.md
@@ -0,0 +1,33 @@
+---
+title: Contribute
+template: docs.html
+sort_by: weight
+page_template: docs_page.html
+aliases:
+  - "/contribute/_index.md"
+weight: 3
+---
+
+# Contribute to Hipcheck
+
+The Hipcheck project is happy to accept contributions!
+
+<div class="grid grid-cols-2 gap-8 mt-8">
+
+{% waypoint(title="Coordinating Changes", path="@/docs/contributing/coordinating-changes.md", icon="user") %}
+A guide to all methods for installing Hipcheck.
+{% end %}
+
+{% waypoint(title="Testing Changes", path="@/docs/contributing/testing.md", icon="cloud-lightning") %}
+Some history on the creation and purpose of Hipcheck.
+{% end %}
+
+{% waypoint(title="Intellectual Property", path="@/docs/contributing/intellectual-property.md", icon="shield") %}
+A walkthrough of running Hipcheck for the first time.
+{% end %}
+
+{% waypoint(title="Describing Changes", path="@/docs/contributing/describing-changes.md", icon="message-circle") %}
+A walkthrough of running Hipcheck for the first time.
+{% end %}
+
+</div>
diff --git a/site/content/docs/contributing/coordinating-changes.md b/site/content/docs/contributing/coordinating-changes.md
@@ -0,0 +1,25 @@
+---
+title: Coordinating Changes
+weight: 1
+---
+
+# Coordinating Changes
+
+For small changes, including improvements to documentation, correction of
+bugs, fixing typos, and general code quality improvements, submitting
+without coordinating with the Hipcheck team is generally fine and
+appreciated!
+
+For larger changes, including the addition of new data sources, new analyses,
+refactoring modules, changing the CLI or configuration, or similar, we
+highly suggest discussing your proposed changes before submission. Often
+this will begin with opening up a GitHub Issue or a Discussion, and for
+larger changes may also involve writing a Request for Discussion (RFD)
+document.
+
+RFD's are how the Hipcheck project manages large scale changes to the tool,
+and are documented more on the RFD's page.
+
+The Hipcheck product roadmap is public, and we always recommend checking
+there to see how your proposed changes may fit into the currently-planned
+work.
diff --git a/site/content/docs/contributing/describing-changes.md b/site/content/docs/contributing/describing-changes.md
@@ -0,0 +1,16 @@
+---
+title: Describing Changes
+weight: 4
+---
+
+# Describing Changes
+
+All commits to Hipcheck are required to follow the Conventional Commits
+specfication. We use this requirement to help us auto-generate material
+for our `CHANGELOG.md` and GitHub Release notes with each new version,
+though we do still double-check and write them by hand.
+
+We also generally try to make sure commits serve a reasonably clear
+purpose, and include comments whenever appropriate to explain the
+reasoning behind what is being changed, or at least link to a GitHub
+Issue or Discussion for further explanation.
diff --git a/site/content/docs/contributing/intellectual-property.md b/site/content/docs/contributing/intellectual-property.md
@@ -0,0 +1,15 @@
+---
+title: Intellectual Property
+weight: 3
+---
+
+# Intellectual Property
+
+When you make contributions to Hipcheck, they're done under the terms
+of the Apache 2.0 license.
+
+Apache 2.0 is approved by the Open Source Initiative (OSI) as an
+open source license, meeting the Open Source Definition.
+
+ChooseALicense.com, a project by GitHub, has a layperson's [breakdown of the
+terms of the Apache 2.0 license](https://choosealicense.com/licenses/apache-2.0/).
diff --git a/site/content/docs/contributing/testing.md b/site/content/docs/contributing/testing.md
@@ -0,0 +1,21 @@
+---
+title: Testing Changes
+weight: 2
+---
+
+# Testing Changes
+
+All changes to Hipcheck must pass continuous integration (CI) tests prior
+to being merged. You can simulate this test suite, at least on your own
+operating system and architecture, using the following command:
+
+```sh
+$ cargo xtask ci
+```
+
+Passing this command is not a _guarantee_ of passing the official CI suite
+on GitHub, but is a good way to approximate things locally.
+
+If you want faster tests locally, we also recommend installing `cargo-nextest`.
+The `cargo xtask ci` command will use it instead of `cargo test` if it's
+installed.
diff --git a/site/content/docs/getting-started/_index.md b/site/content/docs/getting-started/_index.md
@@ -0,0 +1,35 @@
+---
+title: Getting Started
+template: docs.html
+page_template: docs_page.html
+weight: 1
+sort_by: weight
+aliases:
+  - "/quickstart"
+---
+
+# Getting Started
+
+Hello, and welcome! This is a "Quickstart" guide to Hipcheck, which means our
+goal with this guide is to get you up and running as a user of Hipcheck as
+quickly as possible. If you'd like a more thorough guide to Hipcheck which
+explains its core concepts, how it works under the hood, and how to configure
+it to your heart's content, we recommend the [Complete Guide](@/docs/guide/_index.md).
+
+
+<div class="grid grid-cols-2 gap-8 mt-8">
+
+{% waypoint(title="Install Hipcheck", path="@/docs/getting-started/install.md", icon="download") %}
+A guide to all methods for installing Hipcheck.
+{% end %}
+
+{% waypoint(title="Why Hipcheck?", path="@/docs/getting-started/why.md", icon="book-open") %}
+Some history on the creation and purpose of Hipcheck.
+{% end %}
+
+
+{% waypoint(title="Quickstart: Your First Analysis", path="@/docs/getting-started/first-run.md", icon="watch") %}
+A walkthrough of running Hipcheck for the first time.
+{% end %}
+
+</div>
diff --git a/site/content/docs/quickstart/_index.md → ...content/docs/getting-started/first-run.md b/site/content/docs/quickstart/_index.md → ...content/docs/getting-started/first-run.md
@@ -1,23 +1,9 @@
 ---
-title: Quickstart
+title: "Quickstart: Your First Analysis"
+weight: 3
 ---
 
-# Quickstart
-
-Hello, and welcome! This is a "Quickstart" guide to Hipcheck, which means our
-goal with this guide is to get you up and running as a user of Hipcheck as
-quickly as possible. If you'd like a more thorough guide to Hipcheck which
-explains its core concepts, how it works under the hood, and how to configure
-it to your heart's content, we recommend the [Complete Guide](/docs/guide).
-
-## Installing Hipcheck
-
-First, you'll need to install Hipcheck. We __strongly__ recommend using the
-install script if you're on a platform for which we provide prebuilt binaries.
-
-{{ button(link="@/install/_index.md", text="Install Hipcheck") }}
-
-## Your First Hipcheck Run
+# Quickstart: Your First Analysis
 
 With Hipcheck installed, let's use it to analyze something! To do that, we'll
 use the `hc check` subcommand. This command takes a "target" (like a package