feat: add Frequently Asked Questions section to home page

[yibeichan]

What this changes

Adds a Frequently Asked Questions section to the bottom of the home page so first-time visitors can find quick answers (what ReproNim is, who it's for, how to get started, etc.) without having to navigate elsewhere.

Each question is a click-to-expand entry. All entries start collapsed; visitors can have several open at once.

The set of questions ships with 7 entries pulled from existing site copy. Wording is easy to revise — see "How to add or change a question" below.

How to add or change a question

To add, edit, reorder, or remove an FAQ entry, you only edit one file: data/faq.yaml. No template, no layout, no theme code.

- question: Your question goes here?
  answer: |
    Your answer goes here. Markdown works:
    **emphasis**, [links](/about/), bullet lists.

Step-by-step walkthrough (with screenshots-of-source examples) is in docs/maintaining-faq.md. A short pointer was also added to CONTRIBUTING.md.

If a contributor lands in content/_index.md via the site's "Edit this page" link, an HTML comment right next to the FAQ shortcode points them at data/faq.yaml so they don't get lost.

Sharable links to specific answers

Each question has a stable URL anchor. You can share, for example:

https://repronim.org/#faq-how-do-i-get-started

…and the page will open with that question already expanded and scrolled into view. Useful for support emails, Slack replies, and forum posts.

Why three commits

Commit	Purpose
fix: Hextra RSS template override	The Hextra theme template breaks on Hugo 0.160+ (the version most maintainers have locally), preventing hugo server from starting. Netlify pins an older Hugo so production was unaffected, but the local dev workflow was broken. This fixes that.
feat: FAQ section	The actual feature — shortcode, data file, starter content.
docs: move maintainer guide	Spec-process notes that shouldn't live in the repo were removed; the maintainer-facing guide was moved to docs/maintaining-faq.md (outside content/, so it's repo-internal and not published).

Reviewer test plan

Once Netlify spins up the preview deploy:

• Open the preview URL. Scroll past the four section buttons (Getting Started / Tools / Fellowship / Why). The FAQ section should appear below them.
• All entries should be collapsed. Click one — it expands. Click a second — both stay open. Click the first again — it collapses without affecting the second.
• Append #faq-how-do-i-get-started to the preview URL. The page should jump to that question with it already expanded.
• Toggle the site's light/dark theme switch (top-right). The FAQ section should be readable in both modes.
• On data/faq.yaml, click the GitHub pencil to start editing. The header comment explains the schema; the workflow feels like editing any other content page.

What I checked before opening this PR

Ran an automated suite against hugo server (Playwright for browser interactions, axe-core for accessibility, Lighthouse for performance):

Check	Result
Section renders, entries expand/collapse, multiple can be open at once, all collapsed by default	All assertions pass
Deep-link with a valid anchor opens the target; bogus anchor causes no error; in-page hash changes work	All pass
Keyboard-only operation (Tab/Enter/Space, visible focus ring)	All pass
Maintainer-facing build warnings fire on bad input (empty fields, invalid id, duplicate slug)	All four warnings fire correctly
Accessibility scan against WCAG 2.1 AA in both light and dark themes (axe-core)	0 violations
Lighthouse Accessibility score	100/100
Performance impact: LCP with the FAQ vs. without (3 runs each)	−5% — within run-to-run noise; no regression
Removing all FAQ entries (entries: [])	Section disappears entirely; home page renders cleanly

Tooling and full results are reproducible from hugo server; happy to share scripts on request.

Known limitation (not introduced by this PR)

The site's search box (top-right "Search") doesn't currently index the home page, so FAQ content is not findable through site search. This is pre-existing Hextra behavior and is independent of this PR — confirmed by reproducing the same gap on main. If FAQ-via-search is something we want, it's worth a separate issue: either configure Hextra to index the home page, or move the FAQ to a dedicated /faq/ page.

🤖 Generated with Claude Code

[netlify]

✅ Deploy Preview for repronim ready!

Name	Link
🔨 Latest commit	ce32cb5
🔍 Latest deploy log	https://app.netlify.com/projects/repronim/deploys/69f8f5f9d2953a000856bc46
😎 Deploy Preview	https://deploy-preview-468--repronim.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[gemini-code-assist]

Code Review

This pull request introduces a data-driven FAQ section to the home page, featuring a new shortcode, a YAML data file for content management, and comprehensive documentation for maintainers. Additionally, it includes a fix for the RSS template to ensure compatibility with Hugo 0.160+ by transitioning from the legacy author object to site parameters. Feedback focuses on improving the robustness of the RSS template against missing configuration, enhancing the user experience for deep-linked FAQ items by accounting for sticky headers in the CSS, and ensuring the FAQ script handles multiple instances on a single page correctly.

[gemini-code-assist]

Accessing fields on $author will cause a template error if site.Params.author is missing from the configuration. Using default (dict) ensures $author is always an object, making the subsequent .email and .name checks safe even if the author configuration is omitted.

{{- $author := site.Params.author | default (dict) -}}

[gemini-code-assist]

Since the site uses a sticky navigation bar, deep-linking to an FAQ entry (e.g., via /#faq-id) will cause the question to be partially obscured by the header. Adding scroll-margin-top ensures that the element is positioned with enough clearance when scrolled into view by the browser or the scrollIntoView script.

Suggested change

	.rn-faq-item {
	border-top: 1px solid rgba(127, 127, 127, 0.3);
	padding: 0.75rem 0;
	}
	.rn-faq-item {
	border-top: 1px solid rgba(127, 127, 127, 0.3);
	padding: 0.75rem 0;
	scroll-margin-top: 5rem;
	}

[gemini-code-assist]

If this shortcode is used multiple times on the same page, the hashchange event listener will be attached multiple times, leading to redundant execution of the openFromHash function. Adding a global guard ensures the initialization logic runs only once per page load.

Suggested change

	(function () {
	function openFromHash() {
	(function () {
	if (window.rnFaqInitialized) return;
	window.rnFaqInitialized = true;
	function openFromHash() {

[asmacdo]

Thanks @yibeichan!

This raises a good point, its been a while since updating Hugo or the theme. I expect that will need some additional changes on the Netlify side, I'd prefer to do that bump separately though, would you mind opening a separate PR for that?

(I haven't looked but I hope we can also bump the theme and avoid the new override.)

I love the faq idea :)

[chaselgrove]

I'd recommend @memartone and @juliebates have a look at this, since it has echoes of early discussions by the web team about site navigation. At issue is not only the FAQ itself but whether navigation can be improved (see the original comment).

[yibeichan]

Thanks @asmacdo! Split the Hextra RSS-template fix into #470 so this PR is FAQ-only. Force-pushed 001-faq-section to drop the fix: commit; the two remaining commits (feat: FAQ and docs: maintainer guide) are unchanged.

Diff for this PR is now scoped to:

CONTRIBUTING.md                |   4 ++
content/_index.md              |   3 +
data/faq.yaml                  |  66 +++++++++++++++++++++
docs/maintaining-faq.md        |  85 +++++++++++++++++++++++++++
layouts/shortcodes/rn-faq.html | 128 +++++++++++++++++++++++++++++++++++++++++
5 files changed, 286 insertions(+)

#470 is intended as a stop-gap — happy to close it without merging if a Hugo + Hextra bump removes the need.

Re: the gemini-code-assist review feedback (sticky-header offset on deep-link scroll, multiple-FAQ-instances per page, RSS-template robustness) — happy to address any of those that you want addressed in this PR; let me know which (if any) feel worth doing now versus leaving for follow-ups.

cc @memartone @juliebates per @chaselgrove — would love your eyes on the FAQ wording itself, especially the seven starter questions in data/faq.yaml.

[juliebates]

hi all - @yibeichan @asmacdo @chaselgrove @memartone @dnkennedy

Dave thought the website group should discuss FAQ page(s) at this week's meeting, so I haven't tried to type things in here as it seems like a larger conversation, I think this is the second set of FAQs topics to come up recently, so I don't know how to comment yet!
@yibeichan you've done some cool things here!- and @chaselgrove is indeed pointing to some extensive past discussions among the website group and with our user testing that have been factoring in to layout considerations, so that is important/merits consideration in my view as well.

[yibeichan]

Addressed the sticky-header item from gemini-code-assist's review (ce32cb5):

 .rn-faq-item {
   border-top: 1px solid rgba(127, 127, 127, 0.3);
   padding: 0.75rem 0;
+  /* Offset deep-link scroll so the targeted entry lands below the
+     Hextra sticky navbar (--navbar-height) instead of behind it. */
+  scroll-margin-top: calc(var(--navbar-height, 4rem) + 0.5rem);
 }

Verified in Chromium that after scrollIntoView the targeted entry sits below Hextra's navbar (computed scroll-margin-top = 72px; navbar height = 64px). The fallback (4rem) preserves sensible behavior if the theme variable ever goes missing.

Leaving the other two gemini-code-assist items as-is for now:

• Multiple FAQ instances per page — currently the section has a fixed id="rn-faq-heading" and entries are namespaced under faq-.... Two {{< rn-faq >}} calls on the same page would collide on the heading id. No real-use scenario for that today (the shortcode is invoked once on the home page); happy to add an instance counter if you'd like the defensive change.
• RSS template robustness — moot if fix: Bump hextra and hugo #470 is replaced by a Hextra/Hugo bump per @asmacdo's preference. If fix: Bump hextra and hugo #470 ends up merging instead, I can harden the template there.

[yibeichan]

@juliebates it would be great if you could let zoom transcribe your website design meeting, and let me know which items/tasks need my action, then i'll do it.

[juliebates]

@yibeichan @dnkennedy @memartone @asmacdo @chaselgrove Thank you so much @yibeichan, both for creating this example and making it so functional that it really prompts constructive thinking. The website group loves what you've done, and s is still thinking about where to put the FAQs, as well as the overall objectives for them, so we have a few things to flush out yet - but your handiwork will definitely go somewhere! We'll be back in touch after we get things sorted a bit further. Thank you for the inspiration, tangible examples are so useful!

[asmacdo]

Thanks for this, I think an FAQ will be very valuable. I think we probably do want to move it, final location tbd, no need to change that we will do the change when we decide where it ultimately goes (possibly its own page).

IMO, I think we should remove doc/maintaining-faq.md, its a bit heavy. We should have enough in the header of the faq.yaml that folks could edit. And a link to the faq.yaml like "Edit/add an faq entry".

But dont actually do that yet, the web team wants to discuss how to proceed.

[asmacdo]

As discussed in the meeting, we are gonna move this to the Help page, trim this down to a couple of FAQs that we know we want, and we can exercise adding FAQs as we go. I'll take over this one to trim it back/move etc.

@yibeichan thanks again!