Refactor documentation using 11ty

[GaetanBt]

Since Hologram has shown its limits and does not seem to be really maintained, we are considering switching to Eleventy to build the static documentation of the project.

Fixes #294, fixes #369, fixes #359

Get started

npm ci, then npm start and go.

To do

• Update Node version to at least v12.10.0 in the Travis configuration
• Theming:
  • Revise themes markup (remove duplicated <h1>'s, use a list, use h3 for description, references, etc.)
  • Clean input CSS (some prefixes or IE fixes may not be still useful)
  • improve homepage theming
  • responsive!
• Content:
  • run PrismJS on code blocks
    • unescape markup in examples (< and > everywhere -_-)
    • customize Prism theme,
    • render HTML code blocks too!
  • Drop SassDoc to use 11ty, too:
    • drop Sassdoc comments formalism to use the same markdown-based comments that we did for Hologram
    • hook this up in a11yCSS plugin (/util/* as input, _data/sass/api.json as output)
    • add PrismJS scss plugin
    • group categories in TOC and content: maybe reconsider the way we generate json source for API content itself?
    • handle multiple matches in ScssContent regex to ensure separate outputs
    • update table / content styles
    • link to GitHub sources for SCSS code blocks? SassDoc 's very own parser kept track of context for each item, which I don't think we're able to (at least automatically).
    • document Output / Return when appropriate? Or simply drop Return?
    • Ensure to document Requires Maybe another day :D
    • Link things together (Used by, Requires, Tests, etc.)
    • Private access: should it be displayed?
      • maybe another table with return/output and require?
  • Find a way to provide a dynamic <title> to data-generated pages
  • Use a Nunjucks component/macro to gather all "external link icons" in one place (→ finally we simply import a SVG file)
  • Revise way to generate docs' CSS which seems to be a little buggy (maybe have a look at pack11ty)
• Cleanup:
  • Remove all occurrences of "hologram" in code, comments, ...
  • Do not rely on Gulp anymore, thus fixes Switch to stylelint for both CSS and scss lints #410 and fixes Use Autoprefixer #391
  • maybe for CSS & web extension too?
  • Use & update npm scripts and GitHub actions to run, deploy, etc. to fix Switch to GitHub Actions #403
    • Make current actions pass
    • Run Pa11y-ci or axe-linter? The whole website is meant to have issues, so…
    • Add Bundlewatch
    • Deploy previews using Netlify, as done in Chaarts?
  • build site in /docs,
  • set site as 11ty folder instead of src to prevent confusion
  • Cleanup HTML: duplicate IDs, maybe minimisation too?
  • Improve theming a bit to fix Docs theming #395
    • use Autoprefixer for docs CSS
    • switch layout to CSS Grid
    • organize CSS: use Dart Sass, ITCSS, maybe Cube or something?
    • handle CSS live reload, after PostCSS + Autoprefixer + CSSnano.
    • RWD (!)
    • use Fira Sans + Fira Code as variable fonts → The current .woff2 are way lighter thant the available variable fonts.
    • Refactor CSS completely by using sseeeedd's tricks as CSS basis (eg. custom props for font-stacks and color palettes)
    • Prism theming based on sseeeedd
    • Improve focus handling
    • Remove unused CSS (using PurgeCSS or something?) → only got a few .tokens from Prism.
  • Redirect old .html URL's to match the new ones without extension by using the good ol'refresh meta, as done in Bootstrap docs' repo. Is that only needed? Maybe a trailing / would suffice, see Amelia Bellamy-Royds explanations recently.
  • Try to upgrade to eleventy 1.0.0 using eleventy upgrade helper?
  • Check Andy Bell's 11ty-base project for potential improvements.
• Document in README!
• Rebase and merge ❤️

After merging

• deploy /docs (in repository settings),
• then drop gh-pages branch and scripts.
• Document in wiki.
• Drop Travis settings in Webhooks.

Remaining issues

Not required to fix right away, but would be good to fix at some point. Maybe simply create issues?

• Improve the way to provide a content block without a Sass comment (see sass/themes/webextension.scss)
• Document Requires
• Display private access
• Document Returns—and improve Outputs?
• "View source" link

[netlify]

✔️ Deploy Preview for a11ycss ready!

🔨 Explore the source changes: 950e19c

🔍 Inspect the deploy log: https://app.netlify.com/sites/a11ycss/deploys/62213a7cca1de200070e27af

😎 Browse the preview: https://deploy-preview-376--a11ycss.netlify.app