Skip to content

Commit 4608f80

Browse files
ctruedenctrueden
committed
Improve statbox documentation
Thanks, Claude Code!
1 parent 9156e7f commit 4608f80

File tree

1 file changed

+200
-15
lines changed

1 file changed

+200
-15
lines changed

‎_pages/editing/statbox.md

Lines changed: 200 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -5,31 +5,216 @@ nav-title: Statbox
55
nav-links: true
66
---
77

8-
This page explains how the "Vital statistics" sidebar works.
8+
The "Vital Statistics" sidebar (statbox) is a dynamic component that displays metadata about software components or people. It appears on the right side of wiki pages when relevant fields are provided in the page's YAML front matter.
99

10-
The sidebar supports quite a few fields; see [this comment](https://github.com/imagej/imagej.github.io/blob/-/_includes/layout/statbox#L31-L75) for a list. Including at least one of these fields will cause the statbox to appear; otherwise, there will be no statbox for the page.
10+
## Overview
1111

12-
## Tips
12+
The statbox operates in two modes:
1313

14-
### Multi-part URL statistics
14+
1. **Manual mode**: You specify metadata fields manually in the page front matter
15+
2. **Automatic mode**: The statbox scrapes information from Maven repositories using JavaScript
1516

16-
Several URL-type stats have multiple related keys (e.g. `release-url` and `release-version`). This is to give you control over displayed text in the limited space of the Vital Statistics box. Note that entering a URL alone is typically insufficient to display: you must also enter a corresponding label.
17+
The two modes can be combined: the automatic population only fills empty fields, which allows manual overrides as needed.
1718

18-
#### Source URLs
19+
## Basic Usage
1920

20-
The `source-url` key is an exception and does not require a corresponding label. Appropriate text will be auto-generated based on the URL domain.
21+
To enable the statbox, add at least one supported field to your page's YAML front matter:
2122

22-
### Keys with Special Values
23+
```yaml
24+
---
25+
title: My Component
26+
name: My Component Name
27+
icon: /media/icons/my-component.png
28+
source-url: https://github.com/myorg/my-component
29+
---
30+
```
31+
32+
## Supported Fields
33+
34+
### General Fields
35+
36+
| Field | Description | Example |
37+
|-------|-------------|---------|
38+
| `icon` | URL of the image icon to show in the statbox header | `/media/icons/fiji.png` |
39+
| `name` | Name of the component or person | `"Fiji"` |
40+
| `affiliation` | Organizational affiliation | `"Fiji University"` |
41+
| `website` | Primary website link | `https://fiji.sc/` |
42+
43+
### Component-Specific Fields
44+
45+
| Field | Description | Example |
46+
|-------|-------------|---------|
47+
| `artifact` | Maven groupId:artifactId for automatic population | `sc.fiji:fiji` |
48+
| `repository` | Maven repository URL (defaults to maven.scijava.org) | `https://repo1.maven.org/maven2` |
49+
| `pom-url` | Direct URL to a POM file for automatic population | `https://raw.githubusercontent.com/imagej/imagej2/main/pom.xml` |
50+
| `source-url` | Source code repository URL | `https://github.com/imagej/imagej2` |
51+
| `source-label` | Custom label for source link (auto-detected if not provided) | `"on GitHub"` |
52+
| `license-url` | License details URL | `/licensing/bsd` |
53+
| `license-label` | License name/label | `"BSD-2"` |
54+
| `release-url` | Latest release URL | `https://github.com/fiji/fiji/releases/latest` |
55+
| `release-version` | Latest release version | `"2.14.0"` |
56+
| `release-date` | Latest release date | `"2023-07-07"` |
57+
| `dev-status` | Development status | `"Active"`, `"Stable"`, `"Unstable"`, `"Obsolete"` |
58+
| `support-status` | Support level | `"Active"`, `"Partial"`, `"Minimal"`, `"None"` |
59+
| `forum-tag` | Image.sc forum tag | `"fiji"` |
60+
61+
### Team Fields
62+
63+
Team fields support multiple people in various formats:
64+
65+
| Field | Description |
66+
|-------|-------------|
67+
| `team-founders` | Project creators |
68+
| `team-leads` | Decision makers |
69+
| `team-developers` | Feature developers |
70+
| `team-debuggers` | Bug fixers |
71+
| `team-maintainers` | Release managers |
72+
| `team-reviewers` | Code reviewers |
73+
| `team-support` | Community support |
74+
| `team-contributors` | Code contributors |
75+
76+
### Person-Specific Fields
77+
78+
| Field | Description | Example |
79+
|-------|-------------|---------|
80+
| `gravatar` | Gravatar hash for profile image | `"abc123def456..."` |
81+
| `forum` | Image.sc Forum username | `"username"` |
82+
| `github` | GitHub username | `"username"` |
83+
| `stackoverflow` | Stack Overflow user ID | `"12345"` |
84+
| `openhub` | Open Hub username | `"username"` |
85+
| `twitter` | Twitter username | `"username"` |
86+
| `linkedin` | LinkedIn profile path | `"in/username"` |
87+
| `researchgate` | ResearchGate profile | `"Username_Name"` |
88+
| `loop` | Loop Research Network ID | `"12345"` |
89+
| `orcid` | ORCID identifier | `"0000-0000-0000-0000"` |
90+
| `researcherid` | ResearcherID | `"A-1234-2023"` |
91+
| `scopus` | Scopus Author ID | `"12345678900"` |
92+
| `arxiv` | arXiv author identifier | `"smith_j_1"` |
93+
| `scholar` | Google Scholar ID | `"AbCdEfGhIjK"` |
94+
| `honorific` | Special community title | `"Grand Poobah"` |
2395

24-
All statbox front matter supports plain-text `key:value` pairs, but several key types have additional value parsing options.
96+
## Advanced Features
97+
98+
### Automatic Population
99+
100+
The most powerful feature is automatic metadata population from Maven artifacts:
101+
102+
```yaml
103+
---
104+
title: Fiji
105+
artifact: sc.fiji:fiji
106+
---
107+
```
108+
109+
This will automatically populate:
110+
- Component name
111+
- Source repository link
112+
- License information
113+
- Latest release version and URL
114+
- Release date
115+
- Team information from POM
116+
- Development and support status
117+
118+
### Multi-part URL Statistics
119+
120+
Several fields have URL/label pairs for better control over display text:
121+
122+
```yaml
123+
---
124+
release-url: https://github.com/imagej/imagej/releases/tag/v2.14.0
125+
release-version: "2.14.0"
126+
license-url: /licensing/bsd
127+
license-label: "BSD-2"
128+
---
129+
```
25130

26-
#### Affiliation
131+
### Source URL Auto-detection
132+
133+
The `source-url` field automatically generates appropriate labels based on the domain:
134+
135+
- `github.com` → "on GitHub"
136+
- `gitlab.com` → "on GitLab"
137+
- `bitbucket.org` → "on BitBucket"
138+
- `sourceforge.net` → "on SourceForge"
139+
- Other URLs → "online"
140+
141+
### Team Member Formats
142+
143+
Team fields accept comma-separated lists with three supported formats:
144+
145+
1. **Wiki people reference**: `@ctrueden` (looks up `/people/ctrueden`)
146+
2. **Name with custom link**: `John Doe | https://johndoe.com`
147+
3. **Plain name**: `Jane Smith`
148+
149+
Example:
150+
```yaml
151+
team-leads: '@ctrueden, Curtis Rueden | /people/curtis-rueden'
152+
team-developers: '@ctrueden, @hinerm, Jane Smith'
153+
```
154+
155+
### Affiliation Links
156+
157+
The `affiliation` field supports the `Name | URL` format:
158+
159+
```yaml
160+
affiliation:
161+
- 'University of Wisconsin-Madison | https://wisc.edu'
162+
- 'Morgridge Institute for Research | https://morgridge.org'
163+
```
164+
165+
## Examples
166+
167+
### Manual Component Example
168+
169+
```yaml
170+
---
171+
title: Fiji
172+
name: Fiji
173+
icon: /media/icons/fiji.png
174+
website: https://fiji.sc
175+
source-url: https://github.com/fiji/fiji
176+
license-url: /licensing/gpl
177+
license-label: GPLv3
178+
release-version: "2.14.0"
179+
release-date: "2023-06-01"
180+
dev-status: Active
181+
support-status: Active
182+
team-leads: '@ctrueden'
183+
team-developers: '@ctrueden, @hinerm'
184+
forum-tag: fiji
185+
---
186+
```
187+
188+
### Automatic Component Example
189+
190+
```yaml
191+
---
192+
title: ImgLib2
193+
artifact: net.imglib2:imglib2
194+
---
195+
```
196+
197+
### Person Example
198+
199+
```yaml
200+
---
201+
title: Curtis Rueden
202+
name: Curtis Rueden
203+
gravatar: abc123def456
204+
affiliation: 'University of Wisconsin-Madison | https://wisc.edu'
205+
website: https://ctrue.name
206+
github: ctrueden
207+
forum: ctrueden
208+
orcid: 0000-0001-7055-6707
209+
scholar: VqJdqBEAAAAJ
210+
honorific: Fiji Maintainer
211+
---
212+
```
27213

28-
* **Name \| link** - Displays the given name with a custom link. This can be absolute (`Google | https://google.com`) or relative (`Google | /people/google`)
214+
## Implementation Details
29215

30-
#### Team members
216+
The statbox is implemented in `_includes/layout/statbox` using Liquid templating and enhanced with JavaScript from `assets/js/maven.js` for automatic population features. When `artifact` or `pom-url` is specified, the JavaScript automatically fetches and parses Maven metadata to populate empty fields.
31217

32-
All of the `team-` sections (e.g. `team-leads`, `team-developers`) accept comma-separated (`,`) lists of one or more individual(s). Each person can be in one of three formats, and the formats can be mixed and matched:
218+
The automatic metadata population logic works best for components using [Maven](/development/maven) as their project management/build tool, and which extend the [pom-scijava parent](https://github.com/scijava/pom-scijava) for build configuration and dependency version management, because pom-scijava [enforces the presence of all the needed metadata](https://github.com/scijava/pom-scijava-base?tab=readme-ov-file#enforcer-rules-declared-in-this-parent). See [here](https://github.com/fiji/fiji/blob/fiji-2.14.0/pom.xml#L16-L178) for an example of how populated metadata might look in your project's `pom.xml` file.
33219

34-
* **@person** - Looks up the person as an id in the [people directory](/people). Note that the `@` can appear anywhere in the id, but can not be the very first character of a value - which can be solved by putting the value in quotes, i.e. `'@ctrueden, @hinerm'`
35-
* **Name \| link** - Displays the given name with a custom link. See also [Affiliation](#affiliation).
220+
The refresh button (⟲) allows users to reload the automatic data, useful when new releases are available.

0 commit comments

Comments
 (0)