diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 965698d8..2bc11c01 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -45,6 +45,10 @@ Every time you add commits to the Pull Request, Netlify will automatically updat Once approved, a maintainer will merge your PR. If your changes need revision, follow their instructions and update your PR. +## Editing the home page FAQ + +The Frequently Asked Questions section on the home page is generated from a single data file: [`data/faq.yaml`](./data/faq.yaml). To add, edit, reorder, or remove a question, edit that file directly via the GitHub web UI (no template or layout changes are needed for ordinary content edits). The file's header comment documents the schema; for a longer walkthrough see [`docs/maintaining-faq.md`](./docs/maintaining-faq.md). + ## Local Development To set up a local development environment: diff --git a/content/_index.md b/content/_index.md index 9c9a9855..424971ac 100644 --- a/content/_index.md +++ b/content/_index.md @@ -62,3 +62,6 @@ A national biotechnology development center dedicated to developing tools and se subtitle="Why reproducible neuroimaging" >}} {{< /rn-buttons >}} + + +{{< rn-faq >}} diff --git a/data/faq.yaml b/data/faq.yaml new file mode 100644 index 00000000..b4f44467 --- /dev/null +++ b/data/faq.yaml @@ -0,0 +1,66 @@ +# Home page Frequently Asked Questions +# +# Each item under `entries:` becomes one expandable question on the home page. +# Order in this list = order on the page. To add, edit, or remove a question, +# just edit this file and commit. +# +# Schema: +# - question: Short question text (plain text, ends with "?"). +# answer: | +# Multi-line Markdown answer. Use the "|" pipe so newlines and +# lists are preserved. Links and **emphasis** work normally. +# id: (optional) explicit URL anchor for deep-linking, e.g. +# "fellowship-apply". Use lowercase, kebab-case. If you set +# this once, you can later reword the question without +# breaking external links to it. +# +# Anchors auto-generated from the question (when no `id:` is set) take the +# form "faq-", e.g. "faq-how-do-i-get-started". Share +# https://repronim.org/#faq-how-do-i-get-started to deep-link directly. +# +# Detailed maintainer guide: docs/maintaining-faq.md + +entries: + - question: What is ReproNim? + answer: | + ReproNim is a national biotechnology development center dedicated to + developing tools and services that increase efficiency, rigor, + reproducibility, transparency, and FAIRness in neuroimaging. See the + [About page](/about/) for the center's history, team, and mission. + + - question: Who is ReproNim for? + answer: | + Researchers, students, data managers, and institutions working with + neuroimaging data — at any stage of a project. If you produce, share, + analyze, or steward MRI/EEG/MEG datasets and want to make that work + more reproducible, ReproNim's tools and guidance are aimed at you. + + - question: How do I get started? + answer: | + The [Getting Started](/resources/getting-started/) page is the best + entry point. From there you can branch into specific + [tools](/resources/tools/) and [tutorials](/resources/) depending on + what you're trying to do. + + - question: Where can I find ReproNim's tools? + answer: | + All recommended tools are catalogued on the + [Tools page](/resources/tools/), with links to documentation, tutorials, + and community help forums for each one. + + - question: How can I participate in the ReproNim community? + answer: | + Visit the [Participate page](/participate/) for current opportunities — + working groups, hackathons, webinars, and ways to contribute to ongoing + projects. + + - question: Where can I get help or attend office hours? + answer: | + Email [info@repronim.org](mailto:info@repronim.org) anytime. Virtual + drop-in office hours run on the first Thursday of every month — see the + [Help page](/help/) for details and additional support resources. + + - question: How do I apply to the ReproNim Fellowship? + answer: | + Application timelines, eligibility, and current cycle details live on + the [Fellowship page](/fellowship/). diff --git a/docs/maintaining-faq.md b/docs/maintaining-faq.md new file mode 100644 index 00000000..4c3f2e45 --- /dev/null +++ b/docs/maintaining-faq.md @@ -0,0 +1,85 @@ +# Maintaining the home page FAQ + +**Audience**: ReproNim maintainers (anyone already comfortable editing site Markdown via GitHub) +**Time to add a new entry**: ~5 minutes + +The Frequently Asked Questions section on the home page is generated from a single data file. This guide walks through adding, editing, reordering, and removing entries — all without touching any layout or template code. + +## TL;DR + +To add an FAQ entry, edit one file: **`data/faq.yaml`** in the repo. Append a new list item under `entries:`, commit, and the question appears on the home page after the next Netlify deploy. + +## Step-by-step: add a new FAQ entry + +1. **Open `data/faq.yaml`** on GitHub. The "Edit this page" workflow that already works for site Markdown also works for data files — open the file in the GitHub UI and click the pencil icon. + +2. **Append a new list item** under `entries:`. Use this template: + + ```yaml + - question: Your question goes here? + answer: | + Your answer goes here. You can use **Markdown**: + - Lists work. + - [Links](/resources/) work. + - `Inline code` works. + ``` + + Notes: + - The `|` after `answer:` is YAML's literal block scalar. It lets you write multi-line Markdown naturally. + - Indent the answer body two spaces past the `answer:` key, as shown. + +3. **(Optional) Set a stable anchor** by adding an explicit `id:` field. Recommended whenever you expect the question wording might change later but you want existing deep links to keep working. + + ```yaml + - id: fellowship-apply + question: How do I apply to the ReproNim Fellowship? + answer: | + See the [Fellowship page](/fellowship/). + ``` + + Without `id:`, the anchor is auto-generated from the question slug — fine for stable wording, but a reworded question changes the URL. + +4. **Commit and push.** Use a conventional-commit message such as `docs: add FAQ entry on fellowship deadlines`. A pull request triggers Netlify's preview deploy; merging to `main` triggers production. + +5. **Verify.** After deploy: + - Open `https://repronim.org/` and scroll to the FAQ section. + - Click your new question; the answer should expand. + - Copy the URL of the question's anchor (right-click the question → "Copy link" works in most browsers, or check the rendered page source for the `
`). + - Paste the deep-link URL in a new tab; confirm the page loads with your entry already expanded and scrolled into view. + +## Step-by-step: edit or remove an entry + +- **Edit**: Change `question` or `answer` in place. Reordering, formatting, and link changes are all in-place edits. +- **Reorder**: Move the list item up or down within `entries:`. Render order = YAML order. +- **Remove**: Delete the list item. If you anticipate that outstanding deep links exist (e.g., the question was linked from an email or another page), consider replacing it with a redirect-style answer that points to the new location instead of deleting outright. + +## Anchor stability tips + +- The auto-generated anchor for a question is `faq-` + the URL-friendly slug of the question. Example: `"How do I get started?"` → `faq-how-do-i-get-started`. +- To preserve a deep link across a rewording, set `id:` to the previous slug **before** changing the question text. Example: change to `id: faq-how-do-i-get-started`, then update `question:` freely. + +## Common pitfalls + +| Symptom | Cause | Fix | +|---------|-------|-----| +| New entry doesn't appear on the home page | YAML indentation is wrong (Netlify build will have failed) | Check the build log on Netlify for a YAML parse error; fix indentation so each list item starts with ` - question:`. | +| Answer renders as a single long line | Used `>` (folded scalar) instead of `|` (literal scalar) for `answer:` | Use `|` to preserve newlines. | +| Markdown link looks like raw text in the answer | The answer string is being treated as plain text | Confirm the YAML uses `answer: |` (with the pipe) and that the answer is indented correctly. The shortcode runs `markdownify` on the value. | +| Deep link doesn't open the entry | Hash in URL doesn't match any entry's id (typo, stale link, or entry was removed) | Verify the current id by inspecting the page or by checking `data/faq.yaml` for an `id:` override. | +| Duplicate ids warning in build log | Two questions slugify to the same anchor (e.g., differ only in punctuation) | Add an explicit `id:` to one of them. | + +## Verifying accessibility (occasional check) + +When the FAQ grows or styles change, run an accessibility check on the home page: + +- **Lighthouse** (Chrome DevTools → Lighthouse → "Accessibility") — score should be ≥ 95 with no FAQ-related findings. +- **axe DevTools** browser extension — run on `/`; confirm no violations under the `.rn-faq` section. +- Keyboard test: Tab to a question; press Enter; press Tab again to confirm focus moves into the answer's links. + +## Where the implementation lives + +- Data: `data/faq.yaml` +- Shortcode template: `layouts/shortcodes/rn-faq.html` +- Invocation: `content/_index.md` (one `{{< rn-faq >}}` line below the `rn-buttons` block) + +If you need to change the section heading, the styling, or the script, edit `layouts/shortcodes/rn-faq.html`. For everyday content edits, you only need `data/faq.yaml`. diff --git a/layouts/shortcodes/rn-faq.html b/layouts/shortcodes/rn-faq.html new file mode 100644 index 00000000..413dd955 --- /dev/null +++ b/layouts/shortcodes/rn-faq.html @@ -0,0 +1,131 @@ +{{- with site.Data.faq -}} +{{- with .entries -}} +{{- $seen := slice -}} +
+

Frequently Asked Questions

+ + {{- range $i, $entry := . }} + {{- $q := $entry.question | default "" -}} + {{- $a := $entry.answer | default "" -}} + {{- if not $q -}} + {{- warnf "rn-faq: skipping entry %d — missing or empty 'question' field" $i -}} + {{- else if not $a -}} + {{- warnf "rn-faq: skipping entry %q — missing or empty 'answer' field" $q -}} + {{- else -}} + {{- $rawId := "" -}} + {{- with $entry.id -}} + {{- $rawId = . -}} + {{- end -}} + {{- $id := "" -}} + {{- if $rawId -}} + {{- $idPattern := `^[a-z0-9][a-z0-9-]*$` -}} + {{- if findRE $idPattern $rawId -}} + {{- $id = $rawId -}} + {{- else -}} + {{- warnf "rn-faq: id %q for question %q is invalid (must match %s); falling back to auto-generated slug" $rawId $q $idPattern -}} + {{- $id = printf "faq-%s" (urlize $q) -}} + {{- end -}} + {{- else -}} + {{- $id = printf "faq-%s" (urlize $q) -}} + {{- end -}} + {{- /* duplicate-id detection: append -2, -3, ... if needed */ -}} + {{- $finalId := $id -}} + {{- $n := 2 -}} + {{- range $seen -}} + {{- if eq . $finalId -}} + {{- $finalId = printf "%s-%d" $id $n -}} + {{- $n = add $n 1 -}} + {{- end -}} + {{- end -}} + {{- if ne $finalId $id -}} + {{- warnf "rn-faq: duplicate anchor for question %q — using %q. Consider setting an explicit 'id:' field in data/faq.yaml." $q $finalId -}} + {{- end -}} + {{- $seen = $seen | append $finalId }} +
+ {{ $q }} +
+ {{ $a | markdownify }} +
+
+ {{- end -}} + {{- end }} + + + + +
+{{- end -}} +{{- end -}}