Comments (15)
I released a first alpha to support the basic approach. A live demo is available on https://version-demo.gethinode.com. The codebase can be found on GitHub. The advanced approach is still work in progress, as well as the guide and docs. Feel free to share your feedback!
from hinode.
I did some testing, and noticed the mounting approach introduces some side effects:
- Page links (
relref
orref
) might become ambiguous - Paga aliases might introduce conflicts
Possibly this could be tackled with a shell script. The script would replace all page links with a version-aware shortcode (e.g. docsref
and strip all aliases from the mounted files. The mounted files would have to be added to .gitignore
.
from hinode.
I released 0.15.0-beta3
to support multi-branch deployments. The demo repository and live demo have been updated too.
Next to some rigorous testing, I plan to work on the following items:
- Add a dismissible alert to the top of the page when a newer version of the docs is available (see Bootstrap PR #38410 for example)
- Update the documentation on https://gethinode.com
- Write a guide on how to enable / configure versioned documentation (basic and advanced)
from hinode.
I have released the final v0.15.0
. You can find a guide on https://gethinode.com/guides/versioning/. The guide includes a link to a demo repository.
I'll close the issue for now, feel free to share your feedback anytime.
from hinode.
Glad you like the theme! I'll add your request to the wishlist.
Strategies
Having looked at some of the discussions and examples, supporting versioned documentation is less trivial than it seems. In general, two strategies could be considered:
- Maintain folders for different versions
- Maintain separate git branches for different versions
Having looked at some of the discussions and examples, it seems the second approach is the best option. It avoids duplicating content and allows for versioning of the generated site itself too (so for example, the site's layout is also version tracked). This is also the approach used by Bootstrap for example.
The drawback of the second approach is that the deployment becomes a bit more complex. Netlify supports so-called branch deploys, in which you can specify which specific branches to deploy and publish. You would need to redirect specific URL's on the server side to make this work.
Branch deploy: a deploy generated from a branch that is not your production branch. Branch deploys are published to a URL which includes the branch name and two hyphens (--) as a prefix. For example, if a branch is called staging, it will deploy to staging--yoursitename.netlify.app. If you use Netlify DNS, you can enable branch subdomains, so the staging branch example would deploy to staging.yourcustomdomain.com.
Approach
The approach consists of the following steps:
-
Enable branch deploys
This is mostly a documentation requirement, and is quite specific to the hosting provider. -
Set server-side redirects
A file./layouts/index.redirects
would contain the server-side redirects that link a content folder to a server-side URL. -
Configure version switch
A version switch would simply navigate to either one of the configured redirects. The available versions should be defined separately, probably inconfig/default/params.toml
.
Examples
Some examples to consider:
- Branch deploys: Dgraph
- Doks versioning
from hinode.
Wow, That's great, thanks for always improving this. π π
from hinode.
Another strategy that comes to mind is to download the content of a specific release to a temp directory. You can then use hugo mount
to add the relevant content to the virtual file system.
Some considerations:
- Avoid duplicating content files (e.g. make use of the repository's tagged releases)
- Avoid hosting-specific deployments (e.g. Netlify branch deployments only work on their platform obviously)
- Ideally the solution is compatible with Linux, macOS, and Windows (although most runners are Linux based, this is not - catering for local development)
- The menu data (
data/docs.yml
) should be mounted too, and should be version aware - The approach should work work both locally and as part of a CI/CD workflow
from hinode.
Great, I will give it a try. Thanks
from hinode.
I did some additional experimentation and concluded the mounting approach has too many unwanted side effects. Instead, I intent to support both other two approaches:
- Basic - Create subfolders within the same repository (e.g.
docs/0.9
,docs/1.0
) - Advanced - Support multi-branch deployments (use Git tags to deploy a versioned branch and redirect them on the server)
The idea is to use the site parameters to define the various versions, and to automatically include them in the navbar. I'm working on a test repository at the moment. I'll also prepare a new guide that illustrates the approach. I'll keep you posted.
from hinode.
I'm working on the advanced approach right now. The redirection for Netlify requires some special configuration.
from hinode.
Thanks so much, it is indeed a significant improvement.
from hinode.
Release 0.15.0-beta5
now introduces support for dismissible alerts. The code checks if the current version is the latest and adds an alert to the top of the page if applicable. The alert is version-aware (meaning it checks each individual version page) and can be dismissed per session - open a new tab to clear the session data.
from hinode.
Great work! Then we can close this issue any time.
from hinode.
Thanks! Does it work as expected?
I'll first finish the docs and guide before closing the issue. I'll release the final v0.15.0
next (if any known issues have been addressed).
from hinode.
I'm quite busy recently and will try it laterοΌ Thanks again
from hinode.
Related Issues (20)
- Add support for native Bootstrap forms
- Make module configurations loosely coupled HOT 3
- [BUG] Support deployment to folder HOT 8
- [BUG] menu items links in navigation bar are incorrect HOT 2
- [BUG] Reduce screen flickering in color mode HOT 2
- [BUG] Sidebar menu does not support multiple languages HOT 1
- [BUG] Sidebar does not support links to external pages
- [BUG] "Last updated" string is not localized with i18n HOT 2
- Save and get the selected language just as the theme switch HOT 15
- [BUG] Prevent recursion when targeting a local page
- [BUG] Fix use of declarations after nested rules (deprecated in Sass 1.77.7)
- [BUG] Purge page translations from search index (FlexSearch)
- [BUG] Blockquote rendering is missing the Bootstrap class HOT 5
- [BUG] File component arguments not working HOT 2
- [BUG] Date defaults to Jan 01 if not specified in metadata
- [BUG] Search background flickers between light and back background when color primary color is used for navbar HOT 9
- [BUG] Flash of unstyled content HOT 1
- [BUG] Theme toggle button flickers HOT 4
- Allow adding aria-label to featured Actions HOT 1
- [BUG] Enable overlay when fixed is turned off
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
π Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. πππ
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google β€οΈ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from hinode.