docs: build with eleventy instead of jekyll

[alxndrsn]

Caution

Please do not merge this PR.

TODO

• fix curlies in generated content
• manifest.appcache
  • file order
  • missing files
  • extra files
• serviceWorker.js
  • missing files (seem to be same as manifest.appcache)
  • cache version number
• feed.xml templating
• fix missing/changed files
  • feed.xml
  • asf.md (if this should be present)
  • blog posts should be in /, not /posts/
• add copy buttons to code examples
• fix code-block indentation
• syntax highlighting
  • likely commits to understand:
    • 09c15b3
    • 45fcb09
    • c27a256
    • 0d8e570
    • 562ccc4
• revert directory renaming?

---

Note

If building the site with this branch after using npm run dev-site-with-docker, generated files in docs/_site/ may belong to root. To fix this:

sudo rm -rf ./docs/_site/

Benefits

• drop ruby dependency

Changes

Eleventy is mostly compatible with Jekyll, so there are minimal changes to the site.

The main changes are:

• collections need to be defined explicitly, and (may) need to change dir
• collections are referenced via collections.x instead of site.x
• site.pages needed to be rebuilt manually
• site.time needed to be recreated, and has changed slightly. This shouldn't be an issue, as it's only used for versioning serviceWorker.js and manifest.appcache, which will change anyway when the site is rebuilt
• collection props are referenced via item.data.x instead of item.x
• page props are renamed from e.g. page.title to global title
• include vs page usage of the posts collection means that post now becomes post.data vs global, depending on how the template is used
• in index.html, remove double-spacing of every line in HTML blocks, as this confuses the new markdown renderer
• syntax highlighting has changed a little:

Before

After

[espy]

Hello @alxndrsn, I gave this a spin and this looks like a great start! Thanks very much.

I have some capacity to continue the work, would you mind if I move this branch into the PouchDB repo and finish it?

[alxndrsn]

I gave this a spin and this looks like a great start!

Thanks for the support! I've been looking for some endorsement at #9135 (comment) before committing to this. If the hoodie team is in favour, perhaps some of you could comment or +1 there?

[espy]

Hello! I've manually tested this on my machine, and it all works very well, thank you for all the work. As far as I can tell, almost everything matches the old site apart from some negligible syntax highlighting differences. I've only found 2 issues that need resolving before merging:

1. Syntax highlighting in the guide section is off (left new, right old):

Many of the guide pages don’t have code fences around some code snippets, for example here, and the js language declaration doesn’t seem to work (a few lines below the previous link). These can both be resolved by declaring the bg and text color on the pre instead of the specific language class, and the bash blocks need to be put inside code fences.

2. The site data now fetching stuff from package.json is cool, but the package.json had the wrong version from the outset, it’s "version": "7.0.0-prerelease", for some reason, and should be 9.0.0.

With those two changes and the resolved conflicts, this seems good to go! URLs all still work, ServiceWorker is serviceworking, the example PouchDB in the dev tools console works… LGTM.

[alxndrsn]

Thanks for the review, and catching these issues 👍

Syntax highlighting in the guide section is off...

Problems were a bit deeper than this, but I've updated to make sure that highlighting is consistent across fenced and indented code blocks, in both markdown and liquid formats.

The site data now fetching stuff from package.json is cool, but

I've reverted to hardcoding the version number - I'm not looking to introduce process changes here, and the version in package.json hasn't been updated on master since 2018.

[alxndrsn]

@espy in your commit at espy/pouchdb-actions-test@2691e89#diff-6744b4267bd2c2918dab97901f10b66cfffb1cff0dddd3c0fd01086f5294f3f0L3-R3, you've reverted the change in liquid templates to add quotes around language names in highlight calls. Did this work without defining a global string js = "js"? If so it could considerably reduce the files touched by this PR.

[alxndrsn]

Problems were a bit deeper than this, but I've updated to make sure that highlighting is consistent across fenced and indented code blocks, in both markdown and liquid formats.

In the end, making indented code blocks work with eleventy's liquid parser caused some knock-on effects - some templated HTML blocks were being rendered instead as code. Instead I've disabled indented code blocks, and converted existing blocks to "fenced" (```) format.

[espy]

@espy in your commit at espy/pouchdb-actions-test@2691e89#diff-6744b4267bd2c2918dab97901f10b66cfffb1cff0dddd3c0fd01086f5294f3f0L3-R3, you've reverted the change in liquid templates to add quotes around language names in highlight calls. Did this work without defining a global string js = "js"? If so it could considerably reduce the files touched by this PR.

Yes, but I did also switch to using eleventy’s syntax highlighting plugin, that’s why that works. If I remember correctly that only required minimal CSS changes, some of which you also have already.

Converting the indented code blocks to fenced ones was also my choice, in my experience being able to avoid significant whitespace like that is always a win 😅