Skip to content

Commit 5a5a295

Browse files
cassidoocassidoo
authored
Add Maintainers in Academia page (#383)
1 parent d2c27a5 commit 5a5a295

7 files changed

Lines changed: 606 additions & 0 deletions

File tree

‎common/academia.js‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
import fs from 'fs'
2+
import path from 'path'
3+
import matter from 'gray-matter'
4+
import { marked } from 'marked'
5+
6+
const ACADEMIA_DIRECTORY = path.join(process.cwd(), 'content', 'academia')
7+
8+
const normalizeMaintainerProfiles = (maintainerProfiles = []) => {
9+
if (Array.isArray(maintainerProfiles)) {
10+
return maintainerProfiles.reduce(
11+
(profiles, entry) => ({ ...profiles, ...entry }),
12+
{},
13+
)
14+
}
15+
16+
if (maintainerProfiles && typeof maintainerProfiles === 'object') {
17+
return maintainerProfiles
18+
}
19+
20+
return {}
21+
}
22+
23+
const parsePost = ({ slug, data, content }) => ({
24+
slug,
25+
name: data.name || '',
26+
institution: data.institution || '',
27+
department: data.department || '',
28+
projectName: data.projectName || '',
29+
projectRepo: data.projectRepo || '',
30+
projectWebsite: data.projectWebsite || '',
31+
maintainerProfiles: normalizeMaintainerProfiles(data.maintainerProfiles),
32+
badges: Array.isArray(data.badges) ? data.badges : [],
33+
description: data.description || '',
34+
content,
35+
})
36+
37+
export const getAcademiaPosts = () => {
38+
if (!fs.existsSync(ACADEMIA_DIRECTORY)) {
39+
return []
40+
}
41+
42+
return fs
43+
.readdirSync(ACADEMIA_DIRECTORY)
44+
.filter((fileName) => fileName.endsWith('.md'))
45+
.map((fileName) => {
46+
const slug = fileName.replace('.md', '')
47+
const markdown = fs.readFileSync(
48+
path.join(ACADEMIA_DIRECTORY, fileName),
49+
'utf-8',
50+
)
51+
const { data, content } = matter(markdown)
52+
53+
return parsePost({ slug, data, content })
54+
})
55+
.sort((postA, postB) => postA.projectName.localeCompare(postB.projectName))
56+
}
57+
58+
export const getAcademiaPostBySlug = (slug) => {
59+
const filePath = path.join(ACADEMIA_DIRECTORY, `${slug}.md`)
60+
61+
if (!fs.existsSync(filePath)) {
62+
return null
63+
}
64+
65+
const markdown = fs.readFileSync(filePath, 'utf-8')
66+
const { data, content } = matter(markdown)
67+
const post = parsePost({ slug, data, content })
68+
69+
return {
70+
...post,
71+
htmlContent: marked(post.content),
72+
}
73+
}

‎components/academia/academia.scss‎

Lines changed: 218 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,218 @@
1+
.academia-list {
2+
padding: spacing(7) spacing(2) 0;
3+
4+
@media (min-width: $lg) {
5+
padding-left: spacing(3);
6+
padding-right: spacing(3);
7+
}
8+
9+
&__intro {
10+
padding: spacing(3);
11+
margin-bottom: spacing(2);
12+
13+
h1 {
14+
@extend %header-2;
15+
margin-bottom: spacing(1.5);
16+
}
17+
18+
p {
19+
@extend %body-1;
20+
color: $white-80;
21+
max-width: 820px;
22+
}
23+
}
24+
25+
&__empty {
26+
@extend %body-1;
27+
color: $white-80;
28+
padding: spacing(3);
29+
border-top: 1px solid $white-50;
30+
}
31+
32+
&__item {
33+
position: relative;
34+
padding: spacing(3);
35+
border-top: 1px solid $white-50;
36+
37+
@extend %background-filter;
38+
}
39+
40+
&__main {
41+
text-align: right;
42+
43+
@media screen and (max-width: $xl) {
44+
text-align: left;
45+
}
46+
}
47+
48+
&__flex {
49+
display: flex;
50+
justify-content: space-between;
51+
flex-wrap: wrap;
52+
}
53+
54+
&__flex div, &__flex p {
55+
max-width: 740px;
56+
}
57+
58+
&__title {
59+
@extend %header-2;
60+
margin-bottom: spacing(1);
61+
}
62+
63+
&__subtitle {
64+
@extend %header-5;
65+
margin-bottom: spacing(2);
66+
}
67+
68+
&__badges {
69+
display: flex;
70+
flex-wrap: wrap;
71+
gap: spacing(1);
72+
margin-bottom: spacing(2);
73+
}
74+
75+
&__description {
76+
@extend %body-1;
77+
color: $white-80;
78+
margin-bottom: spacing(2.5);
79+
}
80+
}
81+
82+
.academia-post {
83+
max-width: 920px;
84+
margin: spacing(6) auto;
85+
padding: 0 spacing(2);
86+
87+
@media (min-width: $md) {
88+
padding: 0 spacing(3);
89+
}
90+
91+
@media (min-width: $lg) {
92+
margin: spacing(8) auto spacing(10);
93+
padding: 0 spacing(4);
94+
}
95+
96+
&__back-link {
97+
@extend %subtitle-1;
98+
display: inline-block;
99+
margin-bottom: spacing(3);
100+
101+
&:hover {
102+
text-decoration: underline;
103+
}
104+
}
105+
106+
&__title {
107+
@extend %header-1;
108+
margin-bottom: spacing(2);
109+
}
110+
111+
&__subtitle {
112+
@extend %header-5;
113+
color: $white-80;
114+
margin-bottom: spacing(3);
115+
}
116+
117+
&__divider {
118+
border: 0;
119+
border-top: 1px solid $white-50;
120+
margin: spacing(3) 0;
121+
}
122+
123+
&__meta {
124+
margin: 0;
125+
}
126+
127+
&__meta-row {
128+
display: grid;
129+
grid-template-columns: 1fr;
130+
row-gap: spacing(0.5);
131+
margin-bottom: spacing(2);
132+
133+
@media (min-width: $md) {
134+
grid-template-columns: 180px 1fr;
135+
column-gap: spacing(1);
136+
align-items: baseline;
137+
}
138+
139+
dt {
140+
@extend %subtitle-1;
141+
color: $white;
142+
}
143+
144+
dd {
145+
margin: 0;
146+
@extend %body-1;
147+
color: $white-80;
148+
149+
a {
150+
text-decoration: underline;
151+
}
152+
}
153+
}
154+
155+
&__badges {
156+
display: flex;
157+
flex-wrap: wrap;
158+
gap: spacing(1);
159+
}
160+
161+
&__content {
162+
@extend %markdown;
163+
@extend %body-1;
164+
165+
color: $white-80;
166+
text-align: justify;
167+
168+
h1,
169+
h2,
170+
h3,
171+
h4,
172+
h5,
173+
h6 {
174+
font-family: $jetbrains;
175+
font-weight: $regular;
176+
color: $white;
177+
margin: spacing(3) 0 spacing(1.5);
178+
line-height: 1.5;
179+
text-align: left;
180+
}
181+
182+
h1 {
183+
font-size: 2rem;
184+
}
185+
186+
h2 {
187+
font-size: 1.75rem;
188+
}
189+
190+
h3 {
191+
font-size: 1.5rem;
192+
}
193+
194+
h4,
195+
h5,
196+
h6 {
197+
font-size: 1.25rem;
198+
}
199+
200+
p,
201+
li {
202+
line-height: 1.8;
203+
}
204+
205+
a {
206+
text-decoration: underline;
207+
}
208+
}
209+
210+
&__footer-links {
211+
@extend %body-1;
212+
color: $white-80;
213+
214+
a {
215+
text-decoration: underline;
216+
}
217+
}
218+
}

‎content/academia/open-biome-maintainer-spotlight.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
---
2+
name: Dr. Test Tester
3+
institution: University of Test
4+
department: Department of Test
5+
projectName: OpenBiome Test
6+
projectRepo: https://github.com/test
7+
projectWebsite: https://github.com
8+
maintainerProfiles:
9+
- linkedin: https://www.linkedin.com/in/github/
10+
- github: https://github.com/
11+
- orcid: https://orcid.org/123456
12+
badges: ["Academic Maintainer", "Verified GitHub Teacher"]
13+
description: "An open source toolkit that helps research labs standardize and analyze environmental microbiome sequencing workflows."
14+
---
15+
16+
(everything below is fake)
17+
18+
When we started OpenBiome Toolkit, the immediate goal was practical: reduce the time students and researchers spend stitching together fragile scripts for sequencing analysis.
19+
20+
At first, our lab used separate notebooks and internal utilities that worked for one project, then broke for the next. As collaborators joined from other universities, the friction became obvious. Everyone had slightly different environments, file conventions, and assumptions.
21+
22+
We decided to build a public, reusable toolkit instead of another private lab pipeline. That shift changed how we think about research software.
23+
24+
## Why maintain in the open
25+
26+
Maintaining an academic open source project means balancing publication cycles, teaching schedules, and community support.
27+
28+
The open model has still been worth it for three reasons:
29+
30+
1. Reproducibility improves when workflows are versioned and visible.
31+
2. Students learn software engineering practices in real projects.
32+
3. Cross-institution collaboration moves faster when teams share a common baseline.
33+
34+
## What the project includes
35+
36+
OpenBiome Toolkit currently provides:
37+
38+
- Data validation commands for sequencing metadata before pipeline execution.
39+
- Reproducible environment setup with pinned dependencies.
40+
- Starter templates for analysis reports and figure generation.
41+
- CI checks so new contributions do not silently change outputs.
42+
43+
## Challenges we are still solving
44+
45+
The hardest part is not the code; it is long-term maintenance planning.
46+
47+
Academic teams naturally rotate as students graduate, and maintainers need clear handoff processes. We now require:
48+
49+
- Contributor onboarding docs for every subsystem.
50+
- Monthly triage and issue labeling.
51+
- Release notes that explain breaking changes in plain language.
52+
53+
## Advice for new academic maintainers
54+
55+
Start smaller than you think.
56+
57+
A focused, reliable tool that solves one painful workflow step is easier to sustain than a broad platform with unclear boundaries. Once you have users and contributors, scope can grow with real feedback.
58+
59+
Open source in academia is not just about sharing code. It is about building durable research infrastructure that outlives a single grant cycle.

0 commit comments

Comments
 (0)