diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ff498ecd51..5ffe5feadd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -117,7 +117,7 @@ Writing a blog post for PouchDB is exactly the same process as other contributio ### Steps 1. Open up an issue proposing the blog post if you need help getting ideas or structuring it. -2. Add yourself as an author to https://github.com/pouchdb/pouchdb/blob/master/docs/_data/authors.yml. (Make sure you have a [Gravatar](http://en.gravatar.com/) too.) +2. Add yourself as an author to https://github.com/pouchdb/pouchdb/blob/master/docs/_data/authors.yml, and optionally add an image of yourself in `/docs/static/img/authors`, check the existing files there for guidance on size and format. 3. Add a new blog post with the date that you expect it will be published (we can always change it later). 4. Write something! 5. Run `npm run build-site` and you will always have a fresh version of the site at localhost:4000. You may need to Cmd-Shift-R or Ctrl-Shift-R (hard refresh) to see the latest version, since we use AppCache. diff --git a/README.md b/README.md index 2cd4886853..0b23839cbf 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,4 @@ -[PouchDB](https://pouchdb.com/) – The Database that Syncs! -========= +# [PouchDB](https://pouchdb.com/) – The Database that Syncs! [](https://github.com/pouchdb/pouchdb/actions/workflows/ci.yml?query=branch%3Amaster) [](https://www.npmjs.com/package/pouchdb) [](https://www.jsdelivr.com/package/npm/pouchdb) @@ -7,25 +6,17 @@ PouchDB is an open-source JavaScript database inspired by [Apache CouchDB](http: PouchDB was created to help web developers build applications that work as well offline as they do online. -Using PouchDB -------------- +## Using PouchDB To get started using PouchDB, check out the [web site](https://pouchdb.com) and [API documentation](https://pouchdb.com/api.html). -Deploying the Documentation Site www.pouchdb.com ------------------------------------------------- - -Doc website deployment is handled automatically once the changes land in `master`. - -Getting Help ------------- +## Getting Help The PouchDB community is active [in `#pouchdb` on the CouchDB Slack](https://join.slack.com/t/couchdb/shared_invite/zt-3aqucllea-C92fkzW5oO_VhllRCqFbcw), in [the Google Groups mailing list](https://groups.google.com/forum/#!forum/pouchdb), and [on StackOverflow](http://stackoverflow.com/questions/tagged/pouchdb). Or you can [mastodon @pouchdb](https://fosstodon.org/@pouchdb)! If you think you've found a bug in PouchDB, please write a reproducible test case and file [a Github issue](https://github.com/pouchdb/pouchdb/issues). -Prerelease builds ----- +## Prerelease builds If you like to live on the bleeding edge, you can build PouchDB from source using these steps: @@ -35,8 +26,7 @@ If you like to live on the bleeding edge, you can build PouchDB from source usin After running these steps, the browser build can be found in `packages/node_modules/pouchdb/dist/pouchdb.js`. -Changelog ----- +## Changelog PouchDB follows [semantic versioning](http://semver.org/). To see a changelog with all PouchDB releases, check out the [Github releases page](https://github.com/pouchdb/pouchdb/releases). @@ -44,9 +34,14 @@ For a concise list of breaking changes, there's the [wiki list of breaking chang Keep in mind that PouchDB is auto-migrating, so a database created in 1.0.0 will still work if you open it in 4.0.0+. Any release containing a migration is clearly marked in the release notes. -Contributing ------------- +## Contributing We're always looking for new contributors! If you'd like to try your hand at writing code, writing documentation, designing the website, writing a blog post, or answering [questions on StackOverflow](http://stackoverflow.com/search?tab=newest&q=pouchdb), then we'd love to have your input. If you have a pull request that you'd like to submit, please read the [contributing guide](https://github.com/pouchdb/pouchdb/blob/master/CONTRIBUTING.md) for info on style, commit message format, and other (slightly!) nitpicky things like that. PouchDB is heavily tested, so you'll also want to check out the [testing guide](https://github.com/pouchdb/pouchdb/blob/master/TESTING.md). + +## The pouchdb.com Website + +The documentation website at [pouchdb.com](pouchdb.com) is also part of this repo, in the `/docs` folder. It has its own `/docs/WEBSITE_README.md` + +Website deployment happens automatically once the changes land in `master`. \ No newline at end of file diff --git a/docs/WEBSITE_README.md b/docs/WEBSITE_README.md new file mode 100644 index 0000000000..23994c5253 --- /dev/null +++ b/docs/WEBSITE_README.md @@ -0,0 +1,53 @@ +# pouchdb.com + +This is the PouchDB documentation site, built with [11ty](http://11ty.dev/), a node.js static site generator. + +To run the site locally, in the repo root: + +```sh +$ npm i +$ npm run build-site +``` + +This starts a development server. It watches your files and should rebuild automatically in most cases, but it doesn’t reload the browser for you. + +You can have full hot reloading, but this doesn’t catch changes to the styles (LESS files): + +```sh +$ npm run build11 -- --serve +``` + +To deactivate the dev server and run a regular build without the file watcher: + +```sh +$ BUILD=1 npm run build-site +``` + +## Testing Serviceworker + +```sh +$ npm i +$ npm run build-site +``` + +By default, SW will only cache the pages you’ve seen plus `offline.html`, which it will show whenever you try to access a page offline that hasn’t been cached. + +To test the "Content updated, reload now?" toast that indicates that a new version of the site is available, run the dev server, make a change to the site (e.g. change some text somewhere), then navigate once or reload the page with a normal (not hard) reload. The update toast should show. When you click it, the page and the serviceworker cache will be updated. + +## PouchDB Version Updates + +If you’re releasing a new PouchDB version, the site also needs some updates: + +1. Replace `docs/static/js/pouchdb.min.js` with your newly built version of the same file (this is the PouchDB that is hosted by the website itself and available in the browser dev console). +2. Update the `version` key in `docs/_data/site.js` to the new PouchDB version. + +Then deploy the webite. + +## Website Deployment + +Currently, the website is deployed manually by members of the team. In the near future, any website changes merged into `master` will be deployed automatically. + +## Technology Choices + +The PouchDB website is over a decade old and some parts of it are somewhat out of date by now, but they haven’t been updated for good reasons. The most significant legacy bit is Bootstrap 3.11 in the LESS version, which depends on JQuery for interactivity. There is currently zero benefit to, for example, migrating to SASS/SCSS here or trying to untangle JQuery from Bootstrap in order to use vanilla JS. A design update is on the horizon, and we’ll take that as an opportunity to remove Bootstrap, LESS and JQuery alltogether and replace everything with vanilla web standard JS and CSS, and maybe a slim UI library for base styling. Then we can also get rid of `/bin/build-site.js` and just use 11ty for everything. Until then, we’re still rocking Bootstrap and JQuery. + diff --git a/docs/_data/authors.json b/docs/_data/authors.json index af09e0a5c2..192e5c8f55 100644 --- a/docs/_data/authors.json +++ b/docs/_data/authors.json @@ -4,62 +4,61 @@ "twitter": "nickcolley", "github": "nickcolley", "www": "http://nickcolley.co.uk", - "gravatar": "d83613912d1a2511a784b99c703bdcf6" + "avatar": "nick_colley.jpeg" }, { "name": "Nolan Lawson", "twitter": "nolanlawson", "github": "nolanlawson", "www": "http://nolanlawson.com", - "gravatar": "c436dec61b906e27c963518d0ef1d972" + "avatar": "nolan_lawson.png" }, { "name": "Dale Harvey", "twitter": "daleharvey", "github": "daleharvey", "www": "http://arandomurl.com", - "gravatar": "030451d8cfc268d666bae9a7fe8d10ec" + "avatar": "dale_harvey.jpeg" }, { "name": "Calvin Metcalf", "twitter": "CWMma", "github": "calvinmetcalf", "www": "http://calvinmetcalf.com/", - "gravatar": "e8153037a068f1c32e546f82729a64a5" + "avatar": "calvin_metcalf.jpeg" }, { "name": "Giovanni Ornaghi", "twitter": "sphaso", "github": "sphaso", "www": "https://it.linkedin.com/in/giovanniornaghi", - "gravatar": "da853b1ad9ebe5e1c3ab5b340bb63b70" + "avatar": "giovanni_ornaghi.jpeg" }, { "name": "Garren Smith", "twitter": "garrensmith", "github": "garrensmith", "www": "http://www.redcometlabs.com", - "gravatar": "15fb22e15587c7c36e0aeb5bf3579b07" + "avatar": "garren_smith.png" }, { "name": "Will Holley", "twitter": "wilhol", "github": "willholley", - "www": "https://github.com/willholley/", - "gravatar": "059d287498c864868b910fb0db7c469b" + "www": "https://github.com/willholley/" }, { "name": "Gareth Bowen", "twitter": "garethjtbowen", "github": "garethbowen", "www": "https://bowenwebdesign.co.nz", - "gravatar": "eda4874d50a06c7a6b231ba3dd29c7c0" + "avatar": "gareth_bowen.png" }, { "name": "Alba Herrerías", "twitter": "alba_dev", "github": "AlbaHerrerias", "www": "https://www.albaherrerias.dev", - "gravatar": "da81e745b26ae8ca53fc77538599510f" + "avatar": "alba_herreiras.png" } ] diff --git a/docs/_includes/default.html b/docs/_includes/default.html index 3359d27ba4..d18d7f7c1a 100644 --- a/docs/_includes/default.html +++ b/docs/_includes/default.html @@ -1,26 +1,14 @@ - +