feat: support faq.yml that will be used to generate the FAQs section in the project website

Author: softwareentrepreneer

README.md

@@ -30,7 +30,7 @@
 
 ## Problem
 Going from **writing Python code to publishing and maintaining a package** is **time-consuming**.
-First-time maintainers must learn multiple tools and concepts, e.g. [MyST], [SemVer], CI/CD ([pre-commit] hooks, GitHub workflows), and they often spending hours just to deploy a documentation site whereas well-resourced projects like [PyTorch] and [Scikit-Learn] have **dedicated websites** that serve as their project hubs.
+First-time maintainers must learn multiple tools and concepts, e.g. [MyST], [SemVer], CI/CD ([pre-commit] hooks, GitHub workflows), and they often spend hours just to deploy a documentation site whereas well-resourced projects like [PyTorch] and [Scikit-Learn] have **dedicated websites** that serve as their project hubs.
 
 
 ## Solution
@@ -45,8 +45,8 @@ First-time maintainers must learn multiple tools and concepts, e.g. [MyST], [Sem
 - [x] Go from writing to **website deployment in minutes** — no need to learn any of the underlying tools
 - [x] Centralize all your content in a modern, **unified project website** — from documentation to blog posts
 - [x] Zero-config orchestration — Pre-configured modern tooling with sane defaults (see [Tech Stack](#tech-stack)), so you can start maintaining packages immediately **without learning each tool**
+- [x] **⚡ Full-text search** across **ALL** your content in your website — docs, blogs, tutorials, everything
 - [ ] Export content as PDF — for example, combine all blog posts into a single PDF file
-- [ ] **⚡ Full-text search** across **ALL** your content in your website — docs, blogs, tutorials, everything
 - [ ] **🤖 Embedded AI Chatbot** that answers questions directly using an in-browser LLM — at no cost
 
 ---

afterpython/_website/static/llms.txt

@@ -18,7 +18,7 @@
 
 ## Problem
 Going from **writing Python code to publishing and maintaining a package** is **time-consuming**.
-First-time maintainers must learn multiple tools and concepts, e.g. [MyST], [SemVer], CI/CD ([pre-commit] hooks, GitHub workflows), and they often spending hours just to deploy a documentation site whereas well-resourced projects like [PyTorch] and [Scikit-Learn] have **dedicated websites** that serve as their project hubs.
+First-time maintainers must learn multiple tools and concepts, e.g. [MyST], [SemVer], CI/CD ([pre-commit] hooks, GitHub workflows), and they often spend hours just to deploy a documentation site whereas well-resourced projects like [PyTorch] and [Scikit-Learn] have **dedicated websites** that serve as their project hubs.
 
 ## Solution
 `afterpython` **automates** the tedious parts of Python package maintenance and generates a **project website** for **building community** and **hosting content** such as documentation, **blog posts**, tutorials, examples and more — empowering more developers to write packages with ease.
@@ -31,8 +31,8 @@ First-time maintainers must learn multiple tools and concepts, e.g. [MyST], [Sem
 - [x] Go from writing to **website deployment in minutes** — no need to learn any of the underlying tools
 - [x] Centralize all your content in a modern, **unified project website** — from documentation to blog posts
 - [x] Zero-config orchestration — Pre-configured modern tooling with sane defaults (see [Tech Stack](#tech-stack)), so you can start maintaining packages immediately **without learning each tool**
+- [x] **⚡ Full-text search** across **ALL** your content in your website — docs, blogs, tutorials, everything
 - [ ] Export content as PDF — for example, combine all blog posts into a single PDF file
-- [ ] **⚡ Full-text search** across **ALL** your content in your website — docs, blogs, tutorials, everything
 - [ ] **🤖 Embedded AI Chatbot** that answers questions directly using an in-browser LLM — at no cost
 
 ---
@@ -81,6 +81,8 @@ ap tui
 <!-- - ty -->
 <!-- - [pixi] -->
 
+> Every link below points to the raw markdown source of the page. Fetch any URL directly to read its content as markdown.
+
 ## Documentation
 
 > CLI tool to streamline Python package maintenance and generate a dedicated project website

afterpython/doc/project_website.md

@@ -145,16 +145,35 @@ featured_post = "getting-started.md"
 ```
 
 ---
-## 🚧 Built-in Features
+## Built-in Features
 - full-text search using [PageFind]
-- AI chatbot using [WebLLM]
+- 🚧 AI chatbot using [WebLLM]
+
+### FAQs
+`afterpython/faq.yml` is rendered as the FAQs section on the project website. Each item needs a `question` and `answer`; `category` is optional.
+
+```yaml
+- question: How do I install it?
+  answer: Run `pip install afterpython`, then `ap init`.
+  category: Getting Started
+
+- question: Can I write content in Jupyter notebooks?
+  answer: |
+    Yes — `.ipynb` files in `afterpython/tutorials/` are auto-converted.
+    See the **[quickstart](/doc/quickstart)** for details.
+  category: Getting Started
+
+- question: Is AfterPython free?
+  answer: Yes, it is free and open source.
+```
+
+Both `question` and `answer` accept Markdown — inline code, links, lists, fenced code blocks, etc.
+
+Categories are displayed in the order they first appear in `faq.yml`, so order your questions to control category order.
 
 ### API Reference
 [great-docs]  will be used to build the API Reference section on the project website.
 
-### FAQs
-`faq.yml` will be used as content for the FAQs section on the project website.
-
 ### Google Analytics
 add google analytics support for the entire website
 

afterpython/doc/references/roadmap.md

@@ -4,11 +4,7 @@
 This roadmap is tentative and subject to change
 ```
 
-- add `FAQ` section to the project website and handle `faq.yml`
-- add announcement section to the landing page
-- convert blog posts to format compatible with medium.com and substack.com
 - AI chatbot like kapa.ai using WebLLM
-- full-text search engine using pagefind
 - incremental build, only build changed content (for `ap dev`)
 - integrate with `git-cliff` for changelog generation
 - supports docs built by different engines? e.g. Sphix, MkDocs
@@ -18,6 +14,5 @@ This roadmap is tentative and subject to change
     - very difficult, need to create an interactive UX to show the diffs and let the user choose to merge or not
 - add type checker using `ty`
 - support python 3.14
-- `pcu` should support updating the versions in `pixi.toml`
 - integrate with `pixi`, supports `conda install`
 - support testing across multiple os in ci.yml based on `platforms` set in `pixi.toml`?

afterpython/faq.yml

@@ -0,0 +1,53 @@
+# Exercises:
+# - Plain text, inline code, bold/italic, links, lists, multi-line code blocks
+# - Items with and without `category`
+# - Multiple items sharing a category (to test grouping)
+# - First-appearance category ordering: "Getting Started" -> "Usage" -> "Troubleshooting"
+
+- question: What is AfterPython?
+  answer: AfterPython is a CLI that automates Python project maintenance and generates a project website from your `afterpython/` content folder.
+
+- question: How do I install it?
+  answer: Run `pip install afterpython`, then `ap init` inside your project root. See the **[quickstart](/doc/quickstart)** for the full walkthrough.
+  category: Getting Started
+
+- question: What does `ap init` set up for me?
+  answer: |
+    `ap init` configures:
+    - Pre-commit hooks (ruff, mypy)
+    - Conventional commits via *commitizen*
+    - Semantic-release for versioning
+    - The project website scaffold under `afterpython/`
+  category: Getting Started
+
+- question: How do I run the dev server?
+  answer: |
+    Use `ap dev` from your project root:
+
+    ```bash
+    cd my-project
+    ap dev
+    ```
+
+    This boots the SvelteKit template at `http://localhost:5173`.
+  category: Usage
+
+- question: Can I write content in Jupyter notebooks?
+  answer: Yes — `.ipynb` files in `afterpython/tutorials/` or `afterpython/blog/` are auto-converted. *Marimo* notebooks and **MyST Markdown** are also supported.
+  category: Usage
+
+- question: "Why does `ap build` fail with: `No pyproject.toml found`?"
+  answer: |
+    AfterPython locates the project root by walking up from your current directory looking for `pyproject.toml`. Make sure:
+
+    1. You're inside a Python project
+    2. `pyproject.toml` exists at or above your `cwd`
+    3. You haven't accidentally `cd`'d into a sibling directory
+  category: Troubleshooting
+
+- question: Does this work without a GitHub repository?
+  answer: Yes. The website builds fine locally; only `ap release` and GitHub Pages deploys require a remote.
+
+- question: How do I customize the website's styling?
+  answer: |
+    The frontend is a SvelteKit app under `afterpython/_website/`. Edit `src/app.css` or any component in `src/lib/components/`. The template uses **Tailwind CSS v4** — see the [Tailwind docs](https://tailwindcss.com/docs).