docs: finish Project Website section

Author: softwareentrepreneer

afterpython/doc/myst.md

@@ -3,7 +3,6 @@
 [MyST History]: https://mystmd.org/guide/background#what-is-the-myst-document-engine-and-myst-markdown
 [MyST Overview]: https://mystmd.org/guide/overview
 [Jupyter Notebook]: https://jupyter.org
-[template]: https://github.com/AfterPythonOrg/project-website-template
 [JupyterBook]: https://jupyterbook.org/stable/
 [molab]: https://molab.marimo.io/
 [Marimo]: https://marimo.io/
@@ -61,18 +60,21 @@ Some settings in `myst.yml` may not work as expected, and you may need to report
 Please do **_NOT_** report `mystmd` bugs on `afterpython` repository.
 :::
 
+---
 ### Table of Contents (TOC)
 The `toc` subsection under `project` in `myst.yml` defines how your content is organized.
 
 You can run `myst init --write-toc` in your content directory (e.g., `afterpython/doc/`) to automatically generate a TOC based on your existing content.
 
 *See [Table of Contents](https://mystmd.org/guide/table-of-contents) for more details.*
 
+---
 ### authors.yml
 When you run `ap init`, `afterpython` creates an `authors.yml` file in the `afterpython/` directory and syncs authors from `pyproject.toml`. This allows you to easily manage the authors of your project.
 
 *See [Authorship](https://mystmd.org/guide/authorship#skip-to-frontmatter), you can add social media links to your authors in `authors.yml` (e.g. GitHub, X, etc.)*
 
+---
 #### Change Author at Page Level
 By default, authors defined in `authors.yml` will all be used in `myst.yml` at the project level (see `project.authors` in `myst.yml`). However, you can override this behavior at the page level by adding the `authors` frontmatter at the top of your content (e.g. `doc/your_page.md`):
 ```markdown
@@ -81,3 +83,8 @@ authors:
 - new_author_id_defined_in_authors_yml
 ---
 ```
+
+
+:::{tip}
+This entire documentation is written in MyST Markdown. You can click the "Edit this page" button in the top right corner to see the source code as an example of how to write content in MyST Markdown.
+:::

afterpython/doc/myst.yml

@@ -35,13 +35,7 @@ project:
   toc:
   - file: overview.md
   - file: quickstart.md
-  - title: Walkthrough
-    children:
-    - file: walkthrough/directories.md
-    - file: walkthrough/afterpython_toml.md
-    - file: walkthrough/static_files.md
-    - file: walkthrough/myst_yml.md
-    - file: walkthrough/authors_yml.md
+  - file: walkthrough.md
   - file: concepts.md
   - file: myst.md
   - file: project_website.md

afterpython/doc/project_website.md

@@ -1,5 +1,12 @@
+[project-website-template]: https://github.com/AfterPythonOrg/project-website-template
+[MyST]: https://mystmd.org
+[pdoc]: https://pdoc.dev/docs/pdoc.html
 [PyPI]: https://pypi.org/
+[WebLLM]: https://webllm.mlc.ai/
+[PageFind]: https://pagefind.app/
 [Svelte]: https://svelte.dev/
+[NodeJS]: https://nodejs.org
+[pnpm]: https://www.npmjs.com/package/pnpm
 
 # Project Website
 
@@ -25,37 +32,51 @@ Essentially, it **extends your documentation site into a fully featured website*
 ![project website](../static/project_website.svg)
 :::
 
-
 :::{div}
 :class: hidden dark:block
 ![project website dark](../static/project_website_dark.svg)
 :::
 
-inside `afterpython/` directory:
-Blog/Tutorials/Examples
-content types: doc, blog, tutorial, example, guide, etc.
+During `ap init`, `afterpython` creates a new directory `afterpython/_website/` and initializes it with [project-website-template], which uses [Svelte] and SvelteKit to create the project website and serve the HTML files built by `mystmd` in all of the content folders in `afterpython/` (e.g., `afterpython/doc/`, `afterpython/blog/`)
 
-use a full web ui framework ([Svelte]) to wrap the content and escape the scope of MyST
+This approach brings us into the realm of full-stack web development, which enables us to add features such as an AI chatbot, full-text search engine across the website, etc.
 
-## Homepage
-Currently only your `README.md` is used as the homepage.
 
-### API Reference
-use pdoc
-### FAQs
-faq.yml
-### Compatibility
-support sphinx, mkdocs
+---
+## Website Template Update
+[project-website-template] is a separate repository that will be updated independently of `afterpython` to provide new features and bug fixes for the project website.
+
+When updates are available, run `ap update website`, which will update `afterpython/_website`, and you can start using the new features immediately.
+
+
+:::{warning} Caveat
+`ap update website` will overwrite the existing `afterpython/_website` with the latest [project-website-template]. If you have made any customizations to `afterpython/_website`, they will be lost.
+:::
+
+
+---
+## Customization and Styling
+Since all the code is pulled from [project-website-template] to `afterpython/_website/`, you can customize the project website by modifying the code in `afterpython/_website/src/`.
+
+For example, to change the landing page, which by default displays the `README.md`, you can modify the code in `afterpython/_website/src/routes/+page.svelte`.
+
+> If you don't know Svelte and are using an LLM to code for you, remember to ask it to write in Svelte 5 syntax.
+
 
 ---
+## Work in Progress 🚧
 ## Built-in Features
-- full-text search engine (Work in Progress)
-- AI chatbot (Work in Progress)
+- full-text search using [PageFind]
+- AI chatbot using [WebLLM]
+
+### API Reference
+[pdoc]  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
 
----
-## Website Template Update
-`ap update website`
-Caveat: This will overwrite the existing project website template.
-### Customization and Styling
-can use LLM to code any web components in [Svelte]
+### Compatibility
+Currently `afterpython` only supports content built `mystmd`. It does NOT work with Sphinx, MkDocs etc.

afterpython/doc/quickstart.md

@@ -56,7 +56,7 @@ When using flags, a MyST development server starts for that specific content fol
 All content folders in `afterpython/` (e.g., `afterpython/doc/`, `afterpython/blog/`) are initialized by `myst init` (see [MyST Markdown]), and **each** has a default `index.md` file and a `myst.yml` file for configuration.
 
 :::{seealso}
-To learn more about how to arrange your content in the content folders, see [Table of Contents] or a [Quick Guide about myst.yml](walkthrough/myst_yml.md).
+To learn more about how to arrange your content in the content folders, see [Table of Contents] or a [Quick Guide about myst.yml](myst.md).
 :::
 
 ---

afterpython/doc/references/roadmap.md

@@ -10,3 +10,4 @@ This roadmap is tentative and subject to change
 - incremental build, only build changed content (for `ap dev`)
 - integrate with `git-cliff` for changelog generation
 - integrate with `pixi`, supports `conda install`
+- supports docs built by different engines? e.g. Sphix, MkDocs

afterpython/doc/walkthrough/directories.md renamed to afterpython/doc/walkthrough.md

@@ -3,7 +3,7 @@
 [MyST Markdown]: https://mystmd.org/guide/quickstart
 
 
-# Directories
+# Walkthrough
 After initialization, the following directories are created:
 - `afterpython/`
 - `afterpython/doc/`
@@ -15,3 +15,24 @@ After initialization, the following directories are created:
 The `afterpython/` directory is the main directory that contains all content, while the subdirectories are initialized by `myst init` (see [MyST Markdown]).
 
 > Note that [NodeJS] and [pnpm] will be installed for you by default if they are not already installed
+
+
+## _website/
+
+## Configuration Files
+
+## afterpython.toml
+
+`afterpython.toml` is a configuration file for `afterpython` inside `afterpython/`. Consider it as an extension of `pyproject.toml`, storing extra information of your project such as company name, company URL, project website URL, etc.
+
+
+ruff.toml
+cz.toml
+authors.yml
+myst.yml
+faq.yml
+.pre-commit-config.yaml
+.github/workflows/release.yml
+.github/workflows/deploy.yml
+
+# Static Files