From 52e38db339b352a9a2cf3daa4c52e92388c30631 Mon Sep 17 00:00:00 2001 From: Cassidy James Blaede Date: Wed, 7 Jan 2026 17:00:42 -0700 Subject: [PATCH] Create docs site with mdBook (#34) * Roadmap: formatting improvements for mdbook * gitignore: prevent accidentally adding things * gitignore: ignore bin folder * mdbook: Add required files to make book * mdbook: Point to README as index * mdbook: initial ROOST theme * gitignore: correct formatting * mdbook: add platforms page to book * Workflows: deploy docs to GitHub Pages --- .github/workflows/deploy-docs.yml | 36 +++++++++++++++++++++ .gitignore | 5 +++ README.md | 16 +++++++--- SUMMARY.md | 6 ++++ book.toml | 11 +++++++ roadmap.md | 15 +++++---- theme/css/roost.css | 53 +++++++++++++++++++++++++++++++ theme/fonts/fonts.css | 16 ++++++++++ 8 files changed, 146 insertions(+), 12 deletions(-) create mode 100644 .github/workflows/deploy-docs.yml create mode 100644 .gitignore create mode 100644 SUMMARY.md create mode 100644 book.toml create mode 100644 theme/css/roost.css create mode 100644 theme/fonts/fonts.css diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml new file mode 100644 index 0000000..6520802 --- /dev/null +++ b/.github/workflows/deploy-docs.yml @@ -0,0 +1,36 @@ +name: Deploy Docs +on: + push: + branches: + - main + +jobs: + deploy: + runs-on: ubuntu-latest + permissions: + contents: write + pages: write + id-token: write # To update the deployment status + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + - name: Install latest mdbook + run: | + tag=$(curl 'https://api.github.com/repos/rust-lang/mdbook/releases/latest' | jq -r '.tag_name') + url="https://github.com/rust-lang/mdbook/releases/download/${tag}/mdbook-${tag}-x86_64-unknown-linux-gnu.tar.gz" + mkdir bin + curl -sSL $url | tar -xz --directory=./bin + echo `pwd`/bin >> $GITHUB_PATH + - name: Build Book + run: | + mdbook build + - name: Setup Pages + uses: actions/configure-pages@v4 + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + with: + path: 'book' + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 \ No newline at end of file diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..e1ddf1d --- /dev/null +++ b/.gitignore @@ -0,0 +1,5 @@ +# Prevent adding mdbook binary when running locally +bin/ + +# Don't add the built docs; that's what CI is for +book diff --git a/README.md b/README.md index 942694e..697480b 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,20 @@ -# Community +# Welcome to the ROOST Community! -Documentation and policies for the ROOST organization and open source community. File non-technical or ROOST-wide issues here. +This site hosts documentation and policies for the ROOST organization and open source community. File non-technical or ROOST-wide issues in this [issue tracker][issues]. ## Get Involved -[ROOST](https://roost.tools) is a new and growing organization! We need **your** help to make the community even better: +[ROOST](https://roost.tools) is a new and growing organization! We need **your** help to make the community even better. Here's how you can jump in: + +- **Browse these docs** to better understand ROOST and the community + +- [File an issue][issues] to suggest ideas or tasks -- Browse the docs in this repo -- [File an issue](https://github.com/roostorg/community/issues) to suggest ideas or tasks - [Join our Discord](https://discord.gg/5Csqnw2FSQ) to chat with the team, T&S professionals, open source builders, and other members of the community + - [Start or join a discussion](https://github.com/orgs/roostorg/discussions) on the ROOST org + By participating in our community, you agree to follow the [code of conduct](https://github.com/roostorg/.github/blob/main/CODE_OF_CONDUCT.md) and [contribution guidelines](https://github.com/roostorg/.github/blob/main/CONTRIBUTING.md). Please give them a read to familiarize yourself with them if you haven't already (or if it's been a while). + +[issues]: https://github.com/roostorg/community/issues diff --git a/SUMMARY.md b/SUMMARY.md new file mode 100644 index 0000000..f8c2429 --- /dev/null +++ b/SUMMARY.md @@ -0,0 +1,6 @@ +# Summary + +[Introduction](README.md) +- [Roadmap](roadmap.md) +- [Roles](roles.md) +- [Platforms](platforms.md) diff --git a/book.toml b/book.toml new file mode 100644 index 0000000..e881f37 --- /dev/null +++ b/book.toml @@ -0,0 +1,11 @@ +[book] +title = "ROOST Community" +authors = ["Cassidy James Blaede"] +language = "en" +src = "." + +[build] +build-dir = "./book" + +[output.html] +additional-css = ["theme/css/roost.css"] \ No newline at end of file diff --git a/roadmap.md b/roadmap.md index 2218cee..02f9ca2 100644 --- a/roadmap.md +++ b/roadmap.md @@ -11,9 +11,9 @@ ROOST believes safety infrastructure should be freely available to all regardles [Read more about our approach](https://roost.tools/blog/open-by-design-roost-s-approach-to-safety-tool-development/) and [view our community documentation on GitHub](https://github.com/roostorg/community). -## [The DIRE Framework](https://ssrn.com/abstract=5369158) +### The DIRE Framework -ROOST's projects map to how trust and safety teams actually operate. Our roadmap covers: +ROOST's projects map to how trust and safety teams actually operate using the [DIRE Framework](https://ssrn.com/abstract=5369158). Our roadmap covers: - **Detection**: Identifying potential risks in accounts, behaviors, and content through classifiers, hash matching, and behavioral signals - **Investigation**: Analyzing broad attack patterns by evaluating context beyond individual entities, or diving deep into a single incident @@ -56,14 +56,14 @@ ROOST's two flagship projects are Coop and Osprey, announced in [July 2025](http | UI for analysts to identify abuse patterns and signals | Automated routing of tasks into queues | | Sync and async rule creation and execution | | -## [Osprey]: Investigation +## Osprey: Investigation [(source code)][Osprey] + +![Screenshot of Osprey](https://github.com/roostorg/osprey/raw/main/images/query-and-charts.png) **Current status:** 🟢 v1.0 in production in organizations such as Bluesky that can handle O(1e8) events/day. **Project goal:** Provide rules engine infrastructure that can be hosted within an organization so analysts and safety teams are empowered to conduct their own internal investigations and create rules independently. Scale metadata-based investigations beyond what content-focused solutions can achieve. With empowered analysts, engineering teams can focus on org-specific improvements to increase recall. -![Screenshot of Osprey](https://github.com/roostorg/osprey/raw/main/images/query-and-charts.png) - **Solution:** Osprey is a high-performance rules engine for real-time event processing and behavioral analysis. Safety teams use it to detect patterns across multiple events and conduct sophisticated investigations. **Getting started**: [Development Guide](https://github.com/roostorg/osprey/blob/main/docs/DEVELOPMENT.md) @@ -112,7 +112,7 @@ These features were prioritized after shadowing analysts at Discord and Bluesky These features are exploratory pending v1.1 feedback and resourcing. More information is needed, like whether production deployments reveal specific investigation gaps worth targeting before general-purpose AI assistance. -## [Coop]: Review and Enforcement +## Coop: Review and Enforcement [(source code)][Coop] **Current status:** 🟢 v0 targeting January 2026 @@ -163,7 +163,7 @@ Core features: These features are subject to change based on adopter feedback of v1 and more information is needed. Evaluation datasets co-developed with subject matter expert organizations would allow organizations to test AI-assisted moderation features against real-world content and validated decisions, moving beyond synthetic benchmarks to measure performance on the nuanced cases that matter most. -## [ROOST Model Community]: Detection +## ROOST Model Community: Detection [(link)][ROOST Model Community] **Current status:** 🟢 Active community, [gpt-oss-safeguard model available](https://roost.tools/blog/a-new-milestone-for-open-source-safety-infrastructure-and-transparency/) @@ -269,3 +269,4 @@ Our work with NCMEC focuses on designing the CyberTip reporting function in ROOS [GitHub Discussions]: https://github.com/orgs/roostorg/discussions [^1]: [CyberTipline Data](https://www.missingkids.org/gethelpnow/cybertipline/cybertiplinedata) + diff --git a/theme/css/roost.css b/theme/css/roost.css new file mode 100644 index 0000000..71f1812 --- /dev/null +++ b/theme/css/roost.css @@ -0,0 +1,53 @@ +/* Surgical overrides here; be mindful of alternate themes */ + +:root { + --roost-gray: rgb(187, 193, 190); + --roost-dark: hsl(80, 22%, 13%); + --roost-yellow: rgb(238, 238, 0); + --roost-peach: rgb(247, 187, 128); + --roost-muddy: rgb(229, 217, 136); + + --sidebar-resize-indicator-space: 0; +} + +.light, html:not(.js), .navy { + --bg: rgb(245, 245, 245); + --fg: var(--roost-dark); + + /* --sidebar-bg: var(--roost-dark); */ + --sidebar-bg: oklch(from var(--bg) calc(l * 0.97) c h); + --sidebar-fg: var(--fg); + --sidebar-non-existant: #5c6773; + --sidebar-active: oklch(from var(--roost-muddy) calc(l * 0.5) c h); + --sidebar-spacer: var(--roost-muddy); + --sidebar-header-border-color: oklch(from var(--roost-yellow) calc(l * 0.95) c h); + + --links: inherit; +} + +.navy { + --bg: var(--roost-dark); + --fg: rgba(255, 255, 255, 0.9); + + --sidebar-active: var(--roost-muddy); + + --icons: white; + --icons-hover: var(--roost-yellow); +} + +#mdbook-theme-toggle { + display: none; +} + +#mdbook-menu-bar { + background-color: oklch(from var(--bg) calc(l * 1.2) c h); +} + +#mdbook-sidebar-resize-handle { + background-color: var(--sidebar-bg); +} + +.content a { + font-weight: bold; + text-decoration: underline; +} diff --git a/theme/fonts/fonts.css b/theme/fonts/fonts.css new file mode 100644 index 0000000..3f6bd37 --- /dev/null +++ b/theme/fonts/fonts.css @@ -0,0 +1,16 @@ +@import url('https://fonts.googleapis.com/css2?family=Funnel+Display:wght@300..800&family=Funnel+Sans:ital,wght@0,300..800;1,300..800&display=swap'); + +:root { + font-family: "Funnel Sans", sans-serif; + font-optical-sizing: auto; + font-weight: 400; + font-style: normal; +} + + +h1, h2, h3, h4, h5, h6 { + font-family: "Funnel Display", sans-serif; + font-optical-sizing: auto; + font-weight: 700; + font-style: normal; +} -- 2.51.2