Necessary website changes before the site moves to pouchdb.apache.org
Issue
The PouchDB website will move to https://pouchdb.apache.org in the near future. The workflow to build and deploy the site to there is already in place, but the site currently has a variety of new issues that need to be tackled, and we also want to make some structural changes so we can support versioned docs.
This is a super-issue that collects all the necessary steps.
Apache blocks a variety of external domains, so we need to:
- Remove Gravatar for user avatars and pull the images into the repo.
- Remove Google Analytics.
- Remove Google Fonts and add the fonts to the repo, license permitting (fonts are Lato and Open Sans).
- Remove jQuery entirely or pull it into the repo instead of loading from CDN at
https://code.jquery.com/jquery.min.js. - Pull Bootstrap into the repo instead of loading from CDN at
https://netdna.bootstrapcdn.com/bootstrap/3.1.1/js/bootstrap.min.js. - Find a way to host
pouchdb.min.jsdirectly without building it on every site deploy. Currently, pouchdb.com hosts the library itself (from a CDN athttps://cdn.jsdelivr.net/npm/pouchdb/dist/pouchdb.min.js) so it can be used in the browser terminal. This is a great feature and should be retained somehow.
Restructure the website so we can have versioned docs
[!NOTE] There is now a PR for versioned docs: #9262
Similar to how the CouchDB docs work, we’d like to have versioned docs. This should probably cover not only the /api page, but also /guides and /learn. We need:
- The default docs anyone sees when arriving at pouchdb.apache.org to be
stable, eg. the last proper release. - We also want
latest, which shows the docs as the are in themasterbranch - Then we also want versioned docs, eg.
pouchdb.apache.org/8.0.0/api
We do not need to tie this to the actual release process. All of these pages are written by hand, so we can just create a folder structure that maps to PouchDB releases and change whatever needs to be changed manually. My suggestion for the structure:
Versioned URLs and their sources (same files as before, but in versioned directories)
pouchdb.apache.org/9.0.0/api->/docs/9.0.0/api.htmlpouchdb.apache.org/9.0.0/guides/setup-pouchdb.html->/docs/9.0.0/guides/setup-pouchdb.mdpouchdb.apache.org/8.0.0/adapters.html->/docs/8.0.0/adapters.md- etc.
Latest (points to where the files currently are, in the /docs root)
pouchdb.apache.org/latest/api->/docs/api.htmlpouchdb.apache.org/latest/guides/setup-pouchdb.html->/docs/guides/setup-pouchdb.mdpouchdb.apache.org/latest/adapters.html->/docs/adapters.md
Stable/default (eleventy should reference/copy those from the most recent release)
pouchdb.apache.org/api->/docs/9.0.0/api.htmlpouchdb.apache.org/guides/setup-pouchdb.html->/docs/9.0.0/guides/setup-pouchdb.mdpouchdb.apache.org/adapters.html->/docs/9.0.0/adapters.md
Existing URLs that are redirected from the old domain would just continue working. We’d also need a version switching widget in a corner somewhere.
This is all doable with stock eleventy, and I’ll give this a go since I have time and a fairly good idea of how to achieve this.
Source: apache/pouchdb