docs: improve mkdocs nav, theme, and pretty URLs (#696)
Co-authored-by: Clawdbot <clawdbot@Clawdbots-Mac-mini.local>
taylorcopilot committed
Feb 14, 2026 at 10:58 UTC
382915ffc70df9fdf3d399af8f1e5dfb72a041da
3 files changed
+83
-7
docs/index.md
+40
-7
@@ -1,12 +1,45 @@
1
# SOCFortress CoPilot Documentation
2
3
-This site contains two documentation tracks:
3
+CoPilot is a **single pane of glass** for operating an open‑source SOC/SIEM stack (Wazuh, Graylog, Velociraptor, Grafana, etc.).
4
5
-- **User Guide**: How to use CoPilot day-to-day (SOC operators) and how to configure sources/integrations (admins/engineers).
6
-- **Developer / AI Agent Docs**: Architecture, data flows, schema, and extension playbooks for making safe changes.
5
+This documentation is organized into two tracks:
6
8
-## Start here
7
+- **User Guide** (operators + admins/engineers)
8
+- **Developer / AI Agent Docs** (architecture + safe change playbooks)
9
10
-- If you are an **operator/analyst**: start with **User Guide → Quickstart (Operators)**.
11
-- If you are an **admin/engineer**: start with **User Guide → Quickstart (Admins/Engineers)**.
12
-- If you are making changes to the codebase: start with **Developer / AI Agent Docs → Start Here**.
10
+---
11
+
12
+## Start here (pick your path)
13
+
14
+=== "SOC operator / analyst"
15
+
16
+ You spend most of your time in **Incident Management** (alerts → cases → investigations).
17
+
18
+ - [Quickstart (Operators)](user/operators-quickstart.md)
19
+ - [User Guide Overview](user/overview.md)
20
+ - [Videos (Playlist)](user/videos.md)
21
+
22
+=== "Admin / engineer"
23
+
24
+ You configure **connectors, sources, and integrations** so alerts flow into CoPilot.
25
+
26
+ - [Quickstart (Admins/Engineers)](user/admins-quickstart.md)
27
+ - [Features by Area](user/features.md)
28
+ - [Videos (Playlist)](user/videos.md)
29
+
30
+=== "Developer / AI Agent"
31
+
32
+ You are making changes to the codebase, adding connectors, or debugging flows.
33
+
34
+ - [Start Here](developer/start-here.md)
35
+ - [Architecture](architecture/ARCHITECTURE.md)
36
+ - [Data Flows](architecture/DATA_FLOWS.md)
37
+ - [Database Schema](architecture/DATABASE_SCHEMA.md)
38
+
39
+---
40
+
41
+## How to use this site
42
+
43
+- Use the **left sidebar** (hamburger menu on mobile) to navigate.
44
+- Use **Search** (top bar) to jump straight to a topic.
45
+- Every page is stored in‑repo under `docs/` so it can be updated via PRs.
docs/stylesheets/extra.css
new
+22
@@ -0,0 +1,22 @@
1
+/* Small tweaks to make the landing page + nav feel less cramped */
2
+
3
+/* Slightly wider content for guide-style docs */
4
+.md-content__inner {
5
+ max-width: 900px;
6
+}
7
+
8
+/* Make inline code a touch more readable */
9
+.md-typeset code {
10
+ font-size: 0.9em;
11
+}
12
+
13
+/* Reduce spacing between list items slightly */
14
+.md-typeset ul li,
15
+.md-typeset ol li {
16
+ margin-bottom: 0.15rem;
17
+}
18
+
19
+/* Nicer horizontal rule */
20
+.md-typeset hr {
21
+ border-bottom: 1px solid var(--md-default-fg-color--lightest);
22
+}
mkdocs.yml
+21
@@ -1,28 +1,49 @@
1
site_name: SOCFortress CoPilot Docs
2
site_description: User guide and developer/AI-agent documentation for SOCFortress CoPilot
3
+site_url: https://socfortress.github.io/CoPilot/
4
repo_url: https://github.com/socfortress/CoPilot
5
edit_uri: edit/main/
6
7
+# Use pretty URLs (/user/overview/) instead of .html pages.
8
+use_directory_urls: true
9
+
10
theme:
11
name: material
12
+ language: en
13
features:
14
- navigation.instant
15
+ - navigation.instant.progress
16
- navigation.sections
17
- navigation.expand
18
- navigation.tracking
19
+ - navigation.path
20
- navigation.top
21
+ - navigation.indexes
22
+ - toc.follow
23
- content.code.copy
24
- search.suggest
25
- search.highlight
26
27
+plugins:
28
+ - search
29
+
30
markdown_extensions:
31
- admonition
32
+ - attr_list
33
+ - md_in_html
34
+ - pymdownx.details
35
+ - pymdownx.superfences
36
+ - pymdownx.tabbed:
37
+ alternate_style: true
38
- toc:
39
permalink: true
40
- tables
41
- def_list
42
- footnotes
43
44
+extra_css:
45
+ - stylesheets/extra.css
46
+
47
nav:
48
- Home: index.md
49
- User Guide: