The idea is to provide real documentation pages for extensions. That means they can split it over several pages and don't need to put everything in the readme.
For simplicity, the documentation markdown files will live inside the git repository so everyone can contribute changes and we don't have to build a whole management system :)
Documentation versioning could be used via git itself but that makes later changes a bit difficult so I suggest a filesystem based versioning system.
Repository Structure
├── README.md
├── composer.json
├── config
├── docs
│ └── v1.0
│ ├── contribution.md
│ ├── extend.md
│ ├── installation.md
│ ├── introduction.md
│ ├── menu.yml
│ └── usage.md
├── phpunit.xml.dist
├── src
├── templates
├── tests
└── web
You can see, the git repository contains a docs folder. Inside this folder is one folder for each major/minor (depending on the needs) version of the extension.
The version folder contains a menu.yml file which defines the order and names of the specific documentation pages.
menu.yml
- title: Introduction
file: introduction.md
- title: Installation
file: installation.md
- title: Usage
file: usage.md
- title: Extend the Extension Functionality
file: extend.md
- title: Contribution
file: contribution.md
The menu.yml is just a simple definition file for the navigation.
Note: The files above are just as an example. It's completely up to the extension developer to define the documentation structure for his extension.
Implementation inside the Store
I would suggest the following URL structure for a documentation page:
https://extensions.bolt.cm/view/ohlandt/user-profiles/docs/v1/introduction
So it almost mimics the file structure inside the repository, except that we removed the .md for the URL.
It will also make sense to save the whole documentation somewhere so we don't have to pull it "live" from Github. It would be updated on every update (manually or via hook) in the store.
What I described above is my idea of an easy implementation. But I am also open to suggestions and other ideas :)
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent