Open robsontenorio opened 5 years ago
This is indeed a useful feature, but implementing it must cause breaking changes, first put it aside, and we will introduce RFC process to discuss implementation details.
+1
@ulivz I am considering working on this. Can you provide some guide lines in order to avoid breaking changes?
In this example didnt touch on core components or core vupress files. Just implement a side lib to make it working. The idea is that can be placed on core system and adjust core components in order to get better integration between search and docs versions (in order to avoid search duplications). Or maybe create a new core component SearchDocs (searchbox + docs dropdown)
https://github.com/robsontenorio/lighthouse/tree/vuepress
https://5bf559de05c4170ceead6d8f--lighthouse-vuepress.netlify.com/
docs/
βββ .vuepress/
β βββ config.js # global site config
β βββ versions.json # auto-generated versions file
β
βββ master/
β βββ guides/
β β βββ auth.md # http://mysite.com/master/guides/auth.html
β βββ the-basics/
β β βββ fields.md # http://mysite.com/master/the-basics/fields.html
β β
β βββ sidebar.js # versioned sidebar for this version
β
βββ 2.6/
β βββ ... # same structure from "docs/master/"
β
βββ pages/
β βββ ... # Not versioned, it remains the same for all docs versions
β
βββ package.json # vuepress dependencies
βββ INDEX.md # the beauty home page
sidebar.js
, according version number.# the new file
docs/3.1/guides/cruds.md
# edit the correspondent sidebar
docs/3.1/sidebar.js
.md
extension. The [@paginate](directives.md#paginate) directive is great!
See the [Tutorial](../getting-started/tutorial.md) for more info.
Each subfolder in docs/
will represent a documentation version, except docs/pages/
that will remain the same for all docs versions.
Path | Web route |
---|---|
docs/master/guides/installation.md |
http://mysite.com/master/guides/installation.html |
docs/2.6/guides/installation.md |
http://mysite.com/2.6/guides/installation.html |
docs/pages/users.md |
http://mysite.com/pages/users.html |
You can update multiples docs versions at the same time. Because each docs/
subfolder represents specifics routes when published.
Example: When you change any file from docs/2.6/
, it will publish changes only for 2.6
docs version.
First, finsh your work on docs/master
. A version always should be based from master.
Enter a new version number
yarn docs:version 3.1
Commit and push.
It will be published as the last documentation version.
When tagging a new version, the document versioning mechanism will:
docs/master/
folder contents into a new docs/<version>/
folder.docs/.vuepress/versions.json
Any update on this issue? Would really like to contribute where possible, as i am depending on this feature.
Is this feature being considered for the next version (1.x)?
Now that 1.0 is released, could this be created as a plugin? The plugin api appears to be quite powerful as there is a blog plugin. @robsontenorio would it be possible to move your work to a plugin?
We have been working on a plugin that does versioning in VuePress. It's still in the early stages but we released a first version a couple of days ago. It's pretty similar to how Docusaurus does versioning so there are a few differences to @robsontenorio approach.
vuepress version <sourceDir> <versionNumber>
command to draft new versionswebsite/versioned_docs
when a new version is created. Also snapshots your current sidebar config and stores it with the version.website/pages
by default).Please check out the guide and demo of the plugin here: https://titanium-docs-devkit.netlify.com/guide/versioning.html
The plugin requires a modified theme that is able to handle versioned pages to properly generate links, which you can also find under the link above.
That sounds promising @janvennemann!
Extra pages folder under website/pages for unversioned documents.
Would it make sense to store versioned content in a dedicated folder, instead of non versioned content? This would allow to have extra pages anywhere and not place any extra constraints on folder structure. My intuition is that this could make discriminating versioned content easier as well. :-)
In our use case everything in the docs source folder needs to be versioned anyway and only a few extra pages are exempt from that. That's the reason we choose it that way around. The folder website/pages
is not hardcoded btw and can be configured in the plugin options.
But i see that for others only a specific folder could be of interest to be considered for versioning. I already thought about a exclude
/include
kind of option which could probably allow that. I'll put that on the todo list.
@janvennemann In some docs, we need to display the dynamic version number. After version control is implemented, can you satisfy the variables that reference the version in the document fragment?
Hello! π I think you meant @janvennemann. π Deferring the question to them.
@my9074 Usually you access the version of a particular page via $page.version
. However, I don't think that's easily done in your particular case since it is inside a fenced code block that will be pre-rendered and you don't have access to Vue interpolation there.
There may be a fancy solution using script hoisting and then search & replace a marker with $page.version
but i haven't actually used that yet. You easiest bet is to manually maintain the correct version number in your fenced code blocks.
Just a side-node (or user story): Collaborative docs are often maintained in a VCS like git, on GitHub, or Gitlab servers where you tag a revision of your source tree. From GitHub or GitLab you can directly clone/pull tagged versions of a documentation via URLs.
The OP seems to use the term tagging as adding a new versioned subfolder. If I use the term tag below I refer to git tags, so labels for a particular commit or state of a repository.
While an RFC certainly needs to specify the directory layout for building, thus including version directories makes sense, it would be cool if a final implementation would be able to pull these versioned directories directly from git tags. Then anything apart from master could be .gitignore
-ed. Version state wouldn't become part of the source tree. I think of something similar to what Antora does, for example.
Otherwise it may happen to have a commit with a v2.6 version folder on a "master" branch being changed after a v2.6 git tag has been set on an earlier revision. This undermines git tags, effectively and also makes diffs between versions a lot harder.
Interesting use case! This would require some kind of branch management and logic to merge the docs from different branches into one big final build. Although probably possible with the really powerful plugin system, IMHO that complicates things by a certain degree. However, definitely an interesting alternative to having the versioned docs all checked into one branch.
For reference, take a look on this repo
https://github.com/nuwave/lighthouse
It is a php package with a β/docsβ with vuepress things. On there we just wrote a simple versioning mechanism.
All the docs related things including vuepress and versioning are in β/docsβ. There is a small readme on β/docsβ.
Em ter, 24 de set de 2019 Γ s 08:40, Jan Vennemann notifications@github.com escreveu:
Interesting use case! This would require some kind of branch management and logic to merge the docs from different branches into one big final build. Although probably possible with the really powerful plugin system, IMHO that complicates things by a certain degree. However, definitely an interesting alternative to having the versioned docs all checked into one branch.
β You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/vuejs/vuepress/issues/1018?email_source=notifications&email_token=AAA5BK3R7HS3AUQBSU4WO5LQLH4CLA5CNFSM4GE5VK7KYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOD7OB26I#issuecomment-534519161, or mute the thread https://github.com/notifications/unsubscribe-auth/AAA5BK7CG6I23M5HQ2NBHCLQLH4CLANCNFSM4GE5VK7A .
-- β Robson TenΓ³rio
@janvennemann
This would require some kind of branch management and logic to merge the docs from different branches into one big final build. Although probably possible with the really powerful plugin system, IMHO that complicates things by a certain degree.
I think there could be different incremental steps.
.git
folder, and if so to recreate the vX.Y-folders from the git history. They could be using the git
CLI to find out about tags, tagnames and to restore a particular commit state from the current repo clone, since all info is in its history.Said this, all three stages would be worth their own issues, so I aggree with keeping this one the thread for kind of a "stage 1" solution.
Any word from the Vuepress team if this is something they have on their radar for the near future? Really enjoy using the default theme for our docs, but the lack of versioning is really going to be a problem moving into the future.
It looks like the RFC process is now in place (https://github.com/vuejs/vuepress/tree/master/rfcs).
@robsontenorio , @janvennemann , & @about-code - Y'all look like you have the most fleshed out concepts. Any chance one of you is willing to start the RFC process?
For me it is ok if you copy and past this issue on RFC board. But at this time i am sorry not being available anymore to implement this feature.
Em ter, 5 de nov de 2019 Γ s 18:22, metasean notifications@github.com escreveu:
It looks like the RFC process is now in place ( https://github.com/vuejs/vuepress/tree/master/rfcs).
@robsontenorio https://github.com/robsontenorio , @janvennemann https://github.com/janvennemann , & @about-code https://github.com/about-code - Y'all look like you have the most fleshed out concepts. Any chance one of you is willing to start the RFC process?
β You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/vuejs/vuepress/issues/1018?email_source=notifications&email_token=AAA5BK3Z52IQYHBT42JL74LQSHPZTA5CNFSM4GE5VK7KYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEDELYOI#issuecomment-550026297, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAA5BK6K6DLUM6BRTCVVDIDQSHPZTANCNFSM4GE5VK7A .
-- β Robson TenΓ³rio
@robsontenorio , @janvennemann , & @about-code - Y'all look like you have the most fleshed out concepts [...]
Hmm, I wouldn't use the terms fleshed out or concept myself ;-). My ideas have really just been ideas :-)
Anybody interested in this, please help flesh out https://github.com/vuejs/vuepress/pull/2018 with your ideas, concerns, interests, etc.
Another thing to take into account, is the combination of locale and version. I believe the URL should show as en-GB/1.0/*
, but the file structure should be 1.0/en-GB/*
. This may cause issues with the VuePress path resolving as the URL would not reflect the relative path.
Can we inject scripts in the head based on the sidebar route ?
I have the below sidebar config. Can I Inject particular version of script for each sidebar route ?
{
'/v2/': [ { title: 'Getting Startedv2' }, { title: 'Getting Startedv21' } ],
'/v3/': [ { title: 'Getting Startedv3' }, { title: 'Getting Startedv31' } ]
}
,```
Feature request
https://docusaurus.io/docs/en/versioning
You can use the version script to cut a new documentation version based on the latest content in the docs directory. That specific set of documentation will then be preserved and accessible even as the documentation in the docs directory changes moving forward.
What problem does this feature solve?
Create a mechanism to tag versions of docs.
What does the proposed API look like?
Tag a new doc version
This generate a new folder with tagged docs and includes a dropdown with all available versions. Must be added on default theme.
How should this be implemented in your opinion?
Mostly like Docsaurus does.
Are you willing to work on this yourself?**
No.