Documentation Approach
This site uses Next.js  and Nextra  to display content written in MDX 
Moving Parts
Content locations
| Repo | Location | Description |
|---|---|---|
| wwwlumensalis | src/content | Root content for the site, including the main documentation |
| LCPFDocs | LCPF project documentation, used as a git submodule under src/content/Projects/LCPF/LCPFDocs | |
| LCPF | auto generated API docs in markdown extracted from source using Sphinx/autodoc2 |
Next.js
There isn’t much direct Next.js code (yet) in this project
Nextra
git
Normally this wouldn’t be mentioned, but this project is using a somewhat unusual approach to organizing the content. There is a git repo for the site with the root Next.js / Nextra project and directly authored MDX content under src/content. There is a separate repo containing directly authored MDX content LCPF project documentation, which is used a git submodule under src/content/Projects/LCPF/LCPFDocs on the website repo and under LCPFDocs for the LCPF project repo.
Sphinx / autodoc2
Current Issues
Table of Contents / Tree structure
Nextra supports a table of contents, but there are some problems.
- It takes the structure from the directories and files within the project’s
“content” directory.
- There are ways to rename (as opposed to the file or directory name) or hide each entry
- I have not found any (simple) way to reorganize the structure (e.g. aliases or symbolic links)
using the configuration or directory metadata files
- this leads to some rather deep nesting
- this also is the main reason for project docs requiring dedicated repos, as there isn’t a simple way to tell Nextra to simply ignore unexpected file types
Last updated on