feat: begin prepping zizmor's website

.github/workflows/site.yml

@@ -0,0 +1,49 @@
+name: Deploy zizmor site
+
+on:
+  push:
+    branches:
+      - main
+      - site-staging
+
+  workflow_dispatch:
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+permissions: {}
+
+jobs:
+  deploy:
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Install the latest version of uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: build site
+        run: make site
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site_html
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -1 +1,4 @@
 /target
+
+# website artifacts
+/site_html

CONTRIBUTING.md

@@ -2,69 +2,84 @@
 
 Thank you for your interest in contributing to `zizmor`!
 
-The information below will help you set up a local development environment,
-as well as with performing common development tasks.
+This is intended to be a "high-level" guide with some suggestions
+for ways to contribute. Once you've picked a contribution idea,
+please see our [development docs]
+for concrete guidance on specific development tasks (such as building `zizmor`
+itself or the documentation website).
 
-This is intended to be a "high-level" guide; for concrete development
-goals (such as modifying an audit or contributing a new audit),
-please see our [development docs](./docs/DEVELOPMENT.md).
+## How to contribute
 
-## Requirements
+Here's a short list of steps you can follow to contribute:
 
-`zizmor`'s only development requirement the Rust compiler.
+1. *Figure out what you want to contribute.* See the
+   [contribution ideas](#contribution-ideas) section below if you're looking
+   for ideas!
+2. *File or reply to an issue, if appropriate.* Some contributions require
+   new issues (like new bugs), while others involve an existing issue
+   (like known documentation defects). Others don't require an issue at all,
+   like small typo fixes. In general, if you aren't sure, *error on the side
+   of making or replying to an issue* — it helps maintain shared
+   development context.
+3. *Hack away.* Once you know what you're working on, refer to our
+   [development docs] for help with specific development tasks. And don't be
+   afraid to ask for help!
 
-You can install Rust by following the steps on [Rust's official website].
+## Contribution ideas
 
-[Rust's official website]: https://www.rust-lang.org/tools/install
+Here are some ways that you can contribute to `zizmor`. These aren't the only
+ways; they're just for inspiration.
 
-## Development steps
+### Good first issues
 
-To get started, you'll need to clone the repository and perform a debug build:
+We use the ["good first issue"] label to track issues that we think are
+(somewhat) easy and/or straightforward, making them good choices for an
+early contribution.
 
-```bash
-git clone https://github.com/woodruffw/zizmor
-cd zizmor
-cargo build
-```
+To work on one of these, **please leave a comment** on its issue before opening
+a pull request to make sure nobody else duplicates your work!
 
-Once `cargo build` completes, you should have a functional development
-build of `zizmor`!
+["good first issue"]: https://github.com/woodruffw/zizmor/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22
 
-```bash
-# cargo run -- --help also works
-./target/debug/zizmor --help
-```
+### Writing documentation
 
-## Linting
+One of the best ways to help us with `zizmor` is to help us improve our
+documentation!
 
-`zizmor` is linted with `cargo clippy` and auto-formatted with `cargo fmt`.
-Our CI enforces both, but you should also run them locally to minimize
-unnecessary review cycles:
+Here are some things we could use help with:
 
-```bash
-cargo fmt
-cargo clippy --fix
-```
+* Improving our [CLI usage recipes](https://woodruffw.github.io/zizmor/usage/).
+* Improving the detail in our
+  [audit documentation pages](https://woodruffw.github.io/zizmor/audits/).
+* Improving our internal (Rust API) documentation, especially in conjunction
+  with more unit tests.
 
-## Testing
+More generally, see [issues labeled with `documentation`] for a potential
+list of documentation efforts to contribute on.
 
-`zizmor` uses `cargo test`:
+[issues labeled with `documentation`]: https://github.com/woodruffw/zizmor/issues?q=is%3Aissue+is%3Aopen+label%3Adocumentation
 
-```bash
-cargo test
-```
+### Writing unit tests
 
-## Development practices
+We can always use more unit tests! Pick a part of the Rust codebase and
+start testing.
 
-Here are some guidelines to follow if you're working on `zizmor`:
+Keep the cardinal rule of unit testing in mind: a unit test must test
+**a single unit** of behavior. If it tests more than one unit, then
+consider making it an integration test instead.
+
+### Reducing false positives/negatives in audits
+
+Static analysis is inherently imprecise, and `zizmor` is no exception.
+
+We track imprecision bugs with the ["false positive"] and ["false negative"]
+labels. These can sometimes be tricky to address, so we recommend
+(but don't require) leaving an explanatory comment on the issue before
+beginning a pull request.
+
+["false positive"]: https://github.com/woodruffw/zizmor/issues?q=is%3Aopen+label%3Afalse-positive
+
+["false negative"]: https://github.com/woodruffw/zizmor/issues?q=is%3Aopen+label%3Afalse-negative
+
+[development docs]: https://woodruffw.github.io/zizmor/development/
 
-* *Document internal APIs*. `zizmor` doesn't have a public Rust API (yet),
-  but the internal APIs should be documented *as if* they might become public
-  one day. Plus, well-documented internals make life easier for new
-  contributors.
-* *Write unit tests*. It's easy for small changes in `zizmor`'s internals to
-  percolate into large bugs (e.g. incorrect location information); help us
-  catch these bugs earlier by testing your changes at the smallest unit of
-  behavior.
-* *Test on real inputs*. If you're contributing to or adding a new audit,
-  make sure your analysis is reliable and accurate on non-sample inputs.

Makefile

@@ -0,0 +1,18 @@
+VENV = .venv
+VENV_BIN := $(VENV)/bin
+
+.PHONY: all
+all:
+	@echo "Run my targets individually!"
+
+.PHONY: site
+site: $(VENV)
+	$(VENV_BIN)/mkdocs build
+
+.PHONY: site-live
+site-live: $(VENV)
+	$(VENV_BIN)/mkdocs serve
+
+$(VENV): site-requirements.txt
+	uv venv
+	uv pip install -r site-requirements.txt

README.md

@@ -1,4 +1,4 @@
-# zizmor
+# 🌈 zizmor
 
 [![CI](https://github.com/woodruffw/zizmor/actions/workflows/ci.yml/badge.svg)](https://github.com/woodruffw/zizmor/actions/workflows/ci.yml)
 [![Crates.io](https://img.shields.io/crates/v/zizmor)](https://crates.io/crates/zizmor)
@@ -8,129 +8,17 @@ A tool for finding security issues in GitHub Actions CI/CD setups.
 > [!IMPORTANT]
 > `zizmor` is currently in beta. You will encounter bugs; please file them!
 
-Quick links:
+![](./docs/assets/zizmor-demo.gif)
 
-* [Installation](#installation)
-* [Quick start guide](#quickstart)
-* [Usage](#usage)
-  * [Online and offline use](#online-and-offline-use)
-  * [Output formats](#output-formats)
-  * [Audit documentation](./docs/audit/)
-* [Integration](#integration)
-  * [Use in GitHub Actions](#use-in-github-actions)
-* [Technical details](#technical-details)
-* [Contributing](#contributing)
-* [The name?](#the-name)
+See [`zizmor`'s documentation](https://woodruffw.github.io/zizmor/)
+for [installation steps], as well as a [quickstart] and
+[detailed usage recipes].
 
-Go right to the [Quickstart](#quickstart) or [Usage](#usage) to learn
-how to use `zizmor` locally or in your CI/CD.
+[installation steps]: https://woodruffw.github.io/zizmor/installation/
 
-## Installation
+[quickstart]: https://woodruffw.github.io/zizmor/installation/
 
-You can install `zizmor` from <https://crates.io> via `cargo`:
-
-```bash
-cargo install zizmor
-```
-
-or via [Homebrew](https://brew.sh/):
-
-```bash
-brew install zizmor
-```
-
-## Quickstart
-
-You can run `zizmor` on any file(s) you have locally:
-
-```bash
-# audit a specific workflow
-zizmor my-workflow.yml
-# discovers .github/workflows/*.yml automatically
-zizmor path/to/repo
-```
-
-By default, `zizmor` will emit a Rust-style human-friendly findings, e.g.:
-
-```console
-error[pull-request-target]: use of fundamentally insecure workflow trigger
-  --> /home/william/devel/gha-hazmat/.github/workflows/pull-request-target.yml:20:1
-   |
-20 | / on:
-21 | |   # NOT OK: pull_request_target should almost never be used
-22 | |   pull_request_target:
-   | |______________________^ triggers include pull_request_target, which is almost always used insecurely
-   |
-
-1 findings (0 unknown, 0 informational, 0 low, 0 medium, 1 high)
-```
-
-See the [Usage](#usage) for more examples, including examples of configuration.
-
-## Usage
-
-### Online and offline use
-
-Some of `zizmor`'s audits require access to GitHub's API. `zizmor` will perform
-online audits by default *if* the user has a `GH_TOKEN` specified
-in their environment. If no `GH_TOKEN` is present, then `zizmor` will operate
-in offline mode by default.
-
-Both of these can be made explicit through their respective command-line flags:
-
-```bash
-# force offline, even if a GH_TOKEN is present
-zizmor --offline workflow.yml
-
-# passing a token explicitly will forcefully enable online mode
-zizmor --gh-token ghp-... workflow.yml
-```
-
-### Output formats
-
-`zizmor` always produces output on `stdout`. If a terminal is detected,
-`zizmor` will default to a human-readable diagnostic output; if no terminal
-is detected, `zizmor` will emit JSON.
-
-Output formats can be controlled explicitly via the `--format` option:
-
-```bash
-# force diagnostic output, even if not a terminal
-zizmor --format plain
-
-# emit zizmor's own JSON format
-zizmor --format json
-
-# emit SARIF JSON instead of normal JSON
-zizmor --format sarif
-```
-
-See [Integration](#integration) for suggestions on when to use each format.
-
-## Integration
-
-### Use in GitHub Actions
-
-`zizmor` is trivial to use within GitHub Actions; you can run it just like
-you would locally.
-
-`zizmor --format sarif` specifies [SARIF] as the output format, which GitHub's
-code scanning feature also supports.
-
-See [GitHub's documentation] for advice on how to integrate `zizmor`'s results
-directly into a repository's scanning setup.
-
-For a specific example, see `zizmor`'s own [repository workflow scan].
-GitHub's example of [running ESLint] as a security workflow provides additional
-relevant links.
-
-[SARIF]: https://sarifweb.azurewebsites.net/
-
-[GitHub's documentation]: https://docs.github.com/en/code-security/code-scanning/integrating-with-code-scanning/uploading-a-sarif-file-to-github
-
-[repository workflow scan]: https://github.com/woodruffw/zizmor/blob/main/.github/workflows/zizmor.yml
-
-[running ESLint]: https://docs.github.com/en/code-security/code-scanning/integrating-with-code-scanning/uploading-a-sarif-file-to-github#example-workflow-that-runs-the-eslint-analysis-tool
+[detailed usage recipes]: https://woodruffw.github.io/zizmor/installation/
 
 ## Technical details