Proposal: display multiple versions of docs
- Dominant language
- JavaScript
- Stars
- 31.5k
- Forks
- 5.8k
- Avg merge
- 9d 8h
- Merged PRs (30d)
- 2
Description
# versioning
## Summary
Support for creating docs for different versions.
## Motivation
Versioning support in a documentation generator is quite helping as it helps in supporting separating the docs for different versions. Helps is covering breaking changes. Improves readability.
There are other documentation generators that support this like docusaurus, gitbook etc.
## Detailed Design

This will mainly require to make changes in the `docsify-cli` repo. I don't think we need any changes in the core.
We have great support for having navbar We will make use of that.
- **Configuration**
```js
...
$docsify = {
version : {
// none I guess
}
}
...
```
We can either make it to the navbar.
- **cli command**
```shell
docsify version
```
This will do the following work in sequence
1. it will create a version with name `` in ``
2. check for the navbar markdown content i.e `_navbar.md`
3. if present, good to go. If not present, ask whether the `CLI` can create a new one or not. If the `CLI` is answered with `no`. Stop the operation
4. Update the `_navbar.md` by pretending the content with creating a new list `versions`. First, it will check whether `versions` are present as list heading or not. and inside that, append the list with the ``. Use the AST for the markdown content in order to prepend, append, and check for the `version` list heading. (probably use [`remark`](https://github.com/remarkjs/remark))
5. it will copy-paste every files/folder present in the current directory from where this command is being run i.e `process.cwd()`
to that folder i.e `/`
6. Done
## Documentation
Create a `versioning` page in main docs. Create CLI command docs in the `docsify-cli` and either embed or do the remote rendering in the main docs in order to always show the latest docs
## Drawbacks
Few cons or drawbacks
- it mandates the use of `_navbar.md`
- cant be customizable.
- ``
## Backwards Compatibility Analysis
Not required. As it will need changes in the cli not in the core.
## Alternatives
Manually copy-pasting the files/folder and changing the `_navbar.md`
## Open Questions
- do we want this on the sidebar? I tried but it was not looking good.
## Help Needed
- Please provide some ( edge ) cases where this might break.
- Provide some suggestions to refine the proposal.
- **At last, anyone wants to implement/take this ?**
## Frequently Asked Questions
N/A
## Related Discussions
Forgot the repo + issue. But I did notice few issues and requests for this.
Contributor guide
Assessment
This issue has not been assessed yet.