Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

docs(config): reapply H1 major sections with hero fix (#862)

Maximilian Roosd9ced70893dd
diff --git a/.claude-plugin/skills/worktrunk/reference/config.md b/.claude-plugin/skills/worktrunk/reference/config.md
index 1f54c15a6..0d1a4a510 100644
--- a/.claude-plugin/skills/worktrunk/reference/config.md
+++ b/.claude-plugin/skills/worktrunk/reference/config.md
@@ -59,7 +59,7 @@ test = "npm test"
---
<!-- USER_CONFIG_START -->
-## Worktrunk User Configuration
+# User Configuration
Create with `wt config create`.
@@ -105,7 +105,7 @@ Generate commit messages automatically during merge. Requires an external CLI to
See [LLM commits docs](https://worktrunk.dev/llm-commits/) for setup and [Custom prompt templates](#custom-prompt-templates) for template customization.
-## Commands
+## Command config
### List
@@ -280,7 +280,7 @@ Combine these commits into a single commit message.
---
-## Project configuration
+# Project Configuration
Project config (`.config/wt.toml`) defines lifecycle hooks and project-specific settings. This file is checked into version control and shared with the team. Create with `wt config create --project`.
@@ -302,7 +302,7 @@ platform = "github" # or "gitlab"
---
-## Shell integration
+# Shell Integration
Worktrunk needs shell integration to change directories when switching worktrees. Install with:
@@ -339,6 +339,8 @@ Or via environment variable:
export WORKTRUNK_SKIP_SHELL_INTEGRATION_PROMPT=true
```
+# Other
+
## Environment variables
All user config options can be overridden with environment variables using the `WORKTRUNK_` prefix.
@@ -405,6 +407,8 @@ Usage: <b><span class=c>wt config</span></b> <span class=c>[OPTIONS]</span> <spa
<b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b><span class=c>...</span>
Verbose output (-v: hooks, templates; -vv: debug report)
+# Subcommands
+
## wt config show
Show configuration files & locations.
diff --git a/.claude-plugin/skills/worktrunk/reference/hook.md b/.claude-plugin/skills/worktrunk/reference/hook.md
index 4d74c45e0..449e51634 100644
--- a/.claude-plugin/skills/worktrunk/reference/hook.md
+++ b/.claude-plugin/skills/worktrunk/reference/hook.md
@@ -429,6 +429,8 @@ Usage: <b><span class=c>wt hook</span></b> <span class=c>[OPTIONS]</span> <span
<b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b><span class=c>...</span>
Verbose output (-v: hooks, templates; -vv: debug report)
+# Subcommands
+
## wt hook approvals
Manage command approvals.
diff --git a/.claude-plugin/skills/worktrunk/reference/step.md b/.claude-plugin/skills/worktrunk/reference/step.md
index 77cee4f40..256562b03 100644
--- a/.claude-plugin/skills/worktrunk/reference/step.md
+++ b/.claude-plugin/skills/worktrunk/reference/step.md
@@ -60,6 +60,8 @@ Usage: <b><span class=c>wt step</span></b> <span class=c>[OPTIONS]</span> <span
<b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b><span class=c>...</span>
Verbose output (-v: hooks, templates; -vv: debug report)
+# Subcommands
+
## wt step commit
Stage and commit with LLM-generated message.
diff --git a/dev/config.example.toml b/dev/config.example.toml
index 1d382e644..49abff16e 100644
--- a/dev/config.example.toml
+++ b/dev/config.example.toml
@@ -1,4 +1,4 @@
-# ## Worktrunk User Configuration
+# # User Configuration
#
# Create with `wt config create`.
#
@@ -42,7 +42,7 @@
#
# See LLM commits docs (https://worktrunk.dev/llm-commits/) for setup and Custom prompt templates (#custom-prompt-templates) for template customization.
#
-# ## Commands
+# ## Command config
#
# ### List
#
diff --git a/docs/content/config.md b/docs/content/config.md
index b55dd4c17..7d7400945 100644
--- a/docs/content/config.md
+++ b/docs/content/config.md
@@ -67,7 +67,7 @@ test = "npm test"
---
<!-- USER_CONFIG_START -->
-## Worktrunk User Configuration
+# User Configuration
Create with `wt config create`.
@@ -113,7 +113,7 @@ Generate commit messages automatically during merge. Requires an external CLI to
See [LLM commits docs](@/llm-commits.md) for setup and [Custom prompt templates](#custom-prompt-templates) for template customization.
-## Commands
+## Command config
### List
@@ -288,7 +288,7 @@ Combine these commits into a single commit message.
---
-## Project configuration
+# Project Configuration
Project config (`.config/wt.toml`) defines lifecycle hooks and project-specific settings. This file is checked into version control and shared with the team. Create with `wt config create --project`.
@@ -310,7 +310,7 @@ platform = "github" # or "gitlab"
---
-## Shell integration
+# Shell Integration
Worktrunk needs shell integration to change directories when switching worktrees. Install with:
@@ -347,6 +347,8 @@ Or via environment variable:
export WORKTRUNK_SKIP_SHELL_INTEGRATION_PROMPT=true
```
+# Other
+
## Environment variables
All user config options can be overridden with environment variables using the `WORKTRUNK_` prefix.
@@ -415,6 +417,8 @@ Usage: <b><span class=c>wt config</span></b> <span class=c>[OPTIONS]</span> <spa
Verbose output (-v: hooks, templates; -vv: debug report)
{% end %}
+# Subcommands
+
## wt config show
Show configuration files & locations.
diff --git a/docs/content/hook.md b/docs/content/hook.md
index bf9eec0ba..ae2a09a62 100644
--- a/docs/content/hook.md
+++ b/docs/content/hook.md
@@ -446,6 +446,8 @@ Usage: <b><span class=c>wt hook</span></b> <span class=c>[OPTIONS]</span> <span
Verbose output (-v: hooks, templates; -vv: debug report)
{% end %}
+# Subcommands
+
## wt hook approvals
Manage command approvals.
diff --git a/docs/content/step.md b/docs/content/step.md
index cc13eb6c8..46f04e9f8 100644
--- a/docs/content/step.md
+++ b/docs/content/step.md
@@ -75,6 +75,8 @@ Usage: <b><span class=c>wt step</span></b> <span class=c>[OPTIONS]</span> <span
Verbose output (-v: hooks, templates; -vv: debug report)
{% end %}
+# Subcommands
+
## wt step commit
Stage and commit with LLM-generated message.
diff --git a/docs/sass/custom.scss b/docs/sass/custom.scss
index 54f16d8ea..75688b6ac 100644
--- a/docs/sass/custom.scss
+++ b/docs/sass/custom.scss
@@ -52,11 +52,34 @@ h1, h2, h3, h4, h5, h6 {
}
h1 {
- font-size: 1.75rem;
+ font-size: 1.5rem;
font-weight: 650;
letter-spacing: -0.02em;
- margin-top: 0;
+ margin-top: 2rem;
margin-bottom: 0.5rem;
+ position: relative;
+ width: fit-content; // Block-level but sized to content (for underline effect)
+
+ // Same underline treatment as h2
+ > a {
+ &::after {
+ content: "";
+ position: absolute;
+ left: 0;
+ bottom: -0.3rem;
+ width: 45%;
+ height: 2px;
+ background: var(--wt-color-craft-brown);
+ opacity: 0.5;
+ border-radius: 1px;
+ transition: background 150ms ease-out, opacity 150ms ease-out;
+ }
+
+ &:hover::after {
+ background: var(--wt-color-accent);
+ opacity: 1;
+ }
+ }
}
h2 {
@@ -107,6 +130,7 @@ h4 {
// Heading anchor links - entire heading is clickable
// .heading-anchor = custom anchors in templates, .zola-anchor = Zola-generated
h1 > a.heading-anchor,
+h1 > a.zola-anchor,
h2 > a.zola-anchor,
h3 > a.zola-anchor,
h4 > a.zola-anchor {
@@ -129,6 +153,7 @@ h4 > a.zola-anchor {
}
// Page title heading (used on content pages and hero)
+// These are standalone titles, not section headers, so no underline
.heading-text {
font-family: var(--wt-font-head);
font-size: 1.75rem;
@@ -137,6 +162,12 @@ h4 > a.zola-anchor {
margin-top: 0;
margin-bottom: 0.5rem;
color: var(--wt-color-text);
+ width: auto; // Override h1's fit-content to allow centering
+
+ // Disable the h1 > a underline for page titles
+ > a::after {
+ display: none;
+ }
}
// ============================================================================
@@ -696,7 +727,7 @@ main {
}
.toc-item-child {
- padding: 0 0.45rem 0.2rem 1rem;
+ padding: 0 0.45rem 0.15rem 1rem;
margin: 0 0.4rem;
a {
@@ -720,6 +751,27 @@ main {
font-size: 0.7rem;
}
}
+
+ // H1 entries in TOC - section markers
+ // Same alignment as H2s, distinguished by weight and spacing
+ &.toc-h1 {
+ margin-top: 0.5rem;
+
+ a {
+ font-weight: 600;
+ color: var(--wt-color-text-muted);
+
+ &:hover {
+ color: var(--wt-color-text);
+ background: var(--wt-color-bg-soft);
+ }
+ }
+ }
+
+ // H2s under H1s - same alignment as standalone H2s
+ &.toc-h2-under-h1 {
+ // No extra indent - aligns with standalone H2s
+ }
}
// ============================================================================
diff --git a/docs/templates/macros.html b/docs/templates/macros.html
index 66a636b8e..efbfbe7b5 100644
--- a/docs/templates/macros.html
+++ b/docs/templates/macros.html
@@ -18,10 +18,27 @@
</a>
</div>
- {# Show page TOC for current page (h2s only) #}
+ {# Show page TOC for current page (h1s with nested h2s, or standalone h2s) #}
{% if is_current and current_page.toc %}
{% for h in current_page.toc %}
- {% if h.level == 2 %}
+ {% if h.level == 1 %}
+ <div class="toc-item-child toc-h1">
+ <a class="subtext" href="{{ h.permalink | safe }}">
+ <small>{{ h.title }}</small>
+ </a>
+ </div>
+ {# Show H2 children nested under this H1 #}
+ {% for child in h.children | default(value=[]) %}
+ {% if child.level == 2 %}
+ <div class="toc-item-child toc-h2-under-h1">
+ <a class="subtext" href="{{ child.permalink | safe }}">
+ <small>{{ child.title }}</small>
+ </a>
+ </div>
+ {% endif %}
+ {% endfor %}
+ {% elif h.level == 2 %}
+ {# Standalone H2s (before any H1) #}
<div class="toc-item-child">
<a class="subtext" href="{{ h.permalink | safe }}">
<small>{{ h.title }}</small>
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index 93fe8ea97..d330fa13a 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -1506,7 +1506,7 @@ test = "npm test"
---
<!-- USER_CONFIG_START -->
-## Worktrunk User Configuration
+# User Configuration
Create with `wt config create`.
@@ -1552,7 +1552,7 @@ Generate commit messages automatically during merge. Requires an external CLI to
See [LLM commits docs](@/llm-commits.md) for setup and [Custom prompt templates](#custom-prompt-templates) for template customization.
-## Commands
+## Command config
### List
@@ -1727,7 +1727,7 @@ Combine these commits into a single commit message.
---
-## Project configuration
+# Project Configuration
Project config (`.config/wt.toml`) defines lifecycle hooks and project-specific settings. This file is checked into version control and shared with the team. Create with `wt config create --project`.
@@ -1749,7 +1749,7 @@ platform = "github" # or "gitlab"
---
-## Shell integration
+# Shell Integration
Worktrunk needs shell integration to change directories when switching worktrees. Install with:
@@ -1786,6 +1786,8 @@ Or via environment variable:
export WORKTRUNK_SKIP_SHELL_INTEGRATION_PROMPT=true
```
+# Other
+
## Environment variables
All user config options can be overridden with environment variables using the `WORKTRUNK_` prefix.
diff --git a/src/help.rs b/src/help.rs
index 3a87ab5cd..1e2795cb5 100644
--- a/src/help.rs
+++ b/src/help.rs
@@ -301,6 +301,8 @@ Commands with pages: merge, switch, remove, list"
let subdocs_expanded = expand_subdoc_placeholders(subdocs, sub, &parent_name);
let subdocs_processed = colorize_ci_status_for_html(&subdocs_expanded);
std::println!();
+ std::println!("# Subcommands");
+ std::println!();
std::println!("{}", subdocs_processed.trim());
}
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_create.snap b/tests/snapshots/integration__integration_tests__help__help_config_create.snap
index 31c21b669..453bfc924 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_create.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_create.snap
@@ -50,7 +50,7 @@ Usage: wt config create [OPTIONS]
Creates ~/.config/worktrunk/config.toml with the following content:
- # ## Worktrunk User Configuration
+ # # User Configuration
#
# Create with `wt config create`.
#
@@ -94,7 +94,7 @@ Creates ~/.config/worktrunk/config.toml with the following content:
#
# See LLM commits docs (https://worktrunk.dev/llm-commits/) for setup and Custom prompt templates (#custom-prompt-templates) for template customization.
#
- # ## Commands
+ # ## Command config
#
# ### List
#
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_long.snap b/tests/snapshots/integration__integration_tests__help__help_config_long.snap
index e5f801b1a..132ca2878 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_long.snap
@@ -94,7 +94,7 @@ Show current configuration and file locations:
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
-Worktrunk User Configuration
+USER CONFIGURATION
Create with wt config create.
@@ -138,7 +138,7 @@ Generate commit messages automatically during merge. Requires an external CLI to
See LLM commits docs for setup and Custom prompt templates for template customization.
-Commands
+Command config
List
@@ -292,7 +292,7 @@ Default template:
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
-Project configuration
+PROJECT CONFIGURATION
Project config (.config/wt.toml) defines lifecycle hooks and project-specific settings. This file is checked into version control and shared with the team. Create with wt config create --project.
@@ -312,7 +312,7 @@ See wt hook for hook types, execution order, template variables, and exa
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
-Shell integration
+SHELL INTEGRATION
Worktrunk needs shell integration to change directories when switching worktrees. Install with:
@@ -341,6 +341,8 @@ Or via environment variable:
export WORKTRUNK_SKIP_SHELL_INTEGRATION_PROMPT=true
+OTHER
+
Environment variables
All user config options can be overridden with environment variables using the WORKTRUNK_ prefix.