Use Jekyll for Playbook #355

pezholio · 2020-06-03T08:08:08Z

Fixes #349

Until now, we've used Docsify to power the Playbook, which has worked OK, but it doesn't work at all with JavaScript turned off. We wouldn't accept this in client projects, so it makes sense for the Playbook to meet the same standards.

I've tweaked the Playbook to use Jekyll to build the site, as well as using Webpack to build the limited Javascript functionality. Unfortunately, as the Playbook is a static site, the search won't work without Javascript, but I think this is a fair trade-off.

I've got this branch deploying to Netlify, as it gives us more flexibility in how we deploy the site. Assuming we're OK with this, it'll need a bit more configuration for us to move it across.

You can see the branch deployed the Netlify here - https://competent-bhabha-662efd.netlify.app/

webpack.config.js

_plugins/navigation.rb

_javascripts/src/lib/sidebar_toggle.js

pezholio · 2020-06-03T08:08:43Z

Make the playbook work without JavaScript enabled

erbridge

Not a complete review, but let's also install and use Prettier and ESLint for JavaScript linitng and formatting.

_javascripts/src/lib/search.js

_spec/sidebar_toggle.test.js

_spec/sidebar_navigation.test.js

script/test

CristinaRO · 2020-06-03T11:54:02Z

Running script/bootstrap locally, with a pre-existing installation, it goes well until the last install:

Installing Vale
# github.com/errata-ai/vale/core
../../go/src/github.com/errata-ai/vale/core/util.go:231:8: undefined: strings.ToValidUTF8

CristinaRO · 2020-06-03T12:10:09Z

The scrolling within the file, when clicking an inner anchor link, is very slow and makes me dizzy.

Is it slower because it's on my local, or could it be caused by the change of framework?

pezholio · 2020-06-03T12:41:50Z

@CristinaRO It's caused by the call to scrollIntoView here https://github.com/dxw/playbook/blob/jekyllise-playbook/_javascripts/src/lib/sidebar_navigation.js#L7. I'll have a look if it can be made smoother 🙂

_spec/sidebar_navigation.test.js

jacksonj04 · 2020-06-03T13:59:50Z

In line with running Prettier on JS, we could probably do with running it over all the Markdown as well to ensure it's clean and pretty (as well as throw a test in which stops people checking in messy markdown as well).

webpack.config.js

_spec/sidebar_toggle.test.js

_spec/sidebar_navigation.test.js

_spec/search.test.js

_javascripts/src/lib/sidebar_toggle.js

Gemfile

pezholio · 2020-06-03T14:11:45Z

We do use Hound for linting the Markdown, which makes the visibility of problems easier for non-devs

pezholio · 2020-06-03T14:12:39Z

(Although, at the moment, it seems to be linting the JS and Ruby too, making a helluva lot of noise!)

pezholio · 2020-06-03T15:27:41Z

Running script/bootstrap locally, with a pre-existing installation, it goes well until the last install:
Installing Vale
# github.com/errata-ai/vale/core
../../go/src/github.com/errata-ai/vale/core/util.go:231:8: undefined: strings.ToValidUTF8

@CristinaRO What version of Go are you using? (go version). I could replicate this in CI until I changed the Go version to 1.14

CristinaRO · 2020-06-03T16:25:00Z

@CristinaRO What version of Go are you using? (go version). I could replicate this in CI until I changed the Go version to 1.14

go version go1.12 darwin/amd64

Shouldn't this be part of the bootstrap standard operating procedure though? Or at least specified in the readme / dependencies.

pezholio · 2020-06-03T16:27:56Z

Yep, I’ll add that now I know that’s the issue 👍🏻

erbridge · 2020-06-03T19:19:36Z

https://github.com/syndbg/goenv

pezholio · 2020-06-05T09:07:46Z

Resolve accessibility issues on Playbook

erbridge

I'm happy to help make some of the changes I'm suggesting. Let me know.

.github/workflows/test.yml

.gitignore

erbridge · 2020-06-05T09:40:05Z

.prettierrc

+{
+  "trailingComma": "es5",
+  "singleQuote": true,
+  "semi": false


👎

We're running through Babel, so let's use modern standards and options. And JavaScript has strange behaviour in some cases around semicolons, so let's not turn them off. Defaults are best.

Cool, will do. I fully admit to not really knowing what the "best" way of doing these kind of things are, so appreciate the steer 👍

README.md

_spec/sidebar_navigation.test.js

erbridge · 2020-06-05T09:52:29Z

contributing.md

@@ -1,3 +1,5 @@
+---
+---


We should probably be using the metadata blocks to add things like page titles.

The reason I shied away from this was I didn't want to add any additional workload for non-devs who are contributing to the Playbook. This is a very loosely-held opinion though

It's an upgrade. If they don't do it, it will have the default title and all will be well :).

OK, this is done now 👍

package.json

# Conflicts: # package-lock.json # package.json

This fixes most of the accessilbility issues as outlined in the automated check in #350

Also, use the `*-version` files to specify the versions to use in Github actions

This isn't always available when specifying the ruby version in Actions

Also, move the dmark image out of the `build` folder

Fixes the runtime warning `Liquid Warning: Liquid syntax error (line 70): Expected end_of_string but found id in "{{A SPECIFIC PAGE}}" in guides/plugin-advisories.md`. This did not come up during linting. The text “a specific page” was not appearing, because it was being treated as a placeholder. Use square brackets instead or curly, for consistency with the other example advisories, and capitalise similarly to the other advisories. NB: The existing capitalisation goes against our style recommendations, but it is consistent throughout the plugin advisories guide.

Now the top-level headings are handled in the frontmatter, the way the navigation is handled needs tweaking slightly

We had a link that didn't go anywhere, and now we have the frontmatter, it's easier to get the title of each page to autogenerate a list

.eslintrc.js

.babelrc

README.md

script/bootstrap

script/cibuild

script/test

script/update

erbridge · 2020-06-12T17:21:30Z

Closing in favour of #365.

houndci-bot reviewed Jun 3, 2020

View reviewed changes

erbridge reviewed Jun 3, 2020

View reviewed changes

_javascripts/src/lib/search.js Outdated Show resolved Hide resolved

houndci-bot reviewed Jun 3, 2020

View reviewed changes

pezholio force-pushed the jekyllise-playbook branch from 1d5e634 to 24e1f28 Compare June 3, 2020 10:39

houndci-bot reviewed Jun 3, 2020

View reviewed changes

CristinaRO reviewed Jun 3, 2020

View reviewed changes

script/test Outdated Show resolved Hide resolved

houndci-bot reviewed Jun 3, 2020

View reviewed changes

pezholio force-pushed the jekyllise-playbook branch from 7bafd3f to edcbe81 Compare June 3, 2020 14:21

pezholio force-pushed the jekyllise-playbook branch from f5fdfc0 to c0b3c67 Compare June 3, 2020 15:41

pezholio force-pushed the jekyllise-playbook branch 5 times, most recently from 5149675 to df4fe54 Compare June 5, 2020 08:59

erbridge reviewed Jun 5, 2020

View reviewed changes

pezholio force-pushed the jekyllise-playbook branch from c113415 to eddf518 Compare June 5, 2020 12:24

pezholio and others added 22 commits June 10, 2020 14:36

Add some basic JS tests

c9ef9f3

# Conflicts: # package-lock.json # package.json

Add Prettier to test suite

8a1ca17

Improve sidebar navigation tests

f25af33

Disable JS and Ruby linting with Hound

0212925

Run tests as part of CI

1f61a47

Update documentation

614f86b

Specify Go version

5a740b8

Fix accessibility issues

52b5c38

This fixes most of the accessilbility issues as outlined in the automated check in #350

Make dropdown work on tab focus

f208923

Use version management tools

5db38be

Also, use the `*-version` files to specify the versions to use in Github actions

Install Bundler as part of the CI build

03fd834

This isn't always available when specifying the ruby version in Actions

Use Standardrb to lint Ruby

128d367

Run Prettier across all supported file formats

42f65bd

Use Sass/Webpack for styling

a81713b

Also, move the dmark image out of the `build` folder

Run linting fixes before git commits

27801ec

Add titles to Markdown frontmatter

4303771

Update navigation to remove top-level headings

7b99cad

Now the top-level headings are handled in the frontmatter, the way the navigation is handled needs tweaking slightly

Fix navigation styling

4b0afca

Add a /guides page listing all the subpages

3f89786

We had a link that didn't go anywhere, and now we have the frontmatter, it's easier to get the title of each page to autogenerate a list

Autogenerate navbar

1a9325a

Run Shellcheck as part of test run

3276bde

pezholio force-pushed the jekyllise-playbook branch from 354520a to 3276bde Compare June 10, 2020 13:36

erbridge reviewed Jun 10, 2020

View reviewed changes

erbridge self-assigned this Jun 11, 2020

erbridge mentioned this pull request Jun 12, 2020

Switch to Jekyll over Docsify #365

Merged

3 tasks

erbridge closed this Jun 12, 2020

CristinaRO mentioned this pull request Jun 15, 2020

Playbook doesn't work with JavaScript disabled #349

Closed

erbridge deleted the jekyllise-playbook branch March 16, 2022 09:30

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Use Jekyll for Playbook #355

Use Jekyll for Playbook #355

pezholio commented Jun 3, 2020 •

edited

Loading

pezholio commented Jun 3, 2020

erbridge left a comment

CristinaRO commented Jun 3, 2020

CristinaRO commented Jun 3, 2020

pezholio commented Jun 3, 2020

jacksonj04 commented Jun 3, 2020

pezholio commented Jun 3, 2020

pezholio commented Jun 3, 2020

pezholio commented Jun 3, 2020 •

edited

Loading

CristinaRO commented Jun 3, 2020

pezholio commented Jun 3, 2020

erbridge commented Jun 3, 2020

pezholio commented Jun 5, 2020

erbridge left a comment

erbridge Jun 5, 2020

pezholio Jun 8, 2020

erbridge Jun 5, 2020

pezholio Jun 5, 2020

erbridge Jun 5, 2020

pezholio Jun 8, 2020

erbridge commented Jun 12, 2020

		@@ -1,3 +1,5 @@
		---
		---

Use Jekyll for Playbook #355

Use Jekyll for Playbook #355

Conversation

pezholio commented Jun 3, 2020 • edited Loading

pezholio commented Jun 3, 2020

erbridge left a comment

Choose a reason for hiding this comment

CristinaRO commented Jun 3, 2020

CristinaRO commented Jun 3, 2020

pezholio commented Jun 3, 2020

jacksonj04 commented Jun 3, 2020

pezholio commented Jun 3, 2020

pezholio commented Jun 3, 2020

pezholio commented Jun 3, 2020 • edited Loading

CristinaRO commented Jun 3, 2020

pezholio commented Jun 3, 2020

erbridge commented Jun 3, 2020

pezholio commented Jun 5, 2020

erbridge left a comment

Choose a reason for hiding this comment

erbridge Jun 5, 2020

Choose a reason for hiding this comment

pezholio Jun 8, 2020

Choose a reason for hiding this comment

erbridge Jun 5, 2020

Choose a reason for hiding this comment

pezholio Jun 5, 2020

Choose a reason for hiding this comment

erbridge Jun 5, 2020

Choose a reason for hiding this comment

pezholio Jun 8, 2020

Choose a reason for hiding this comment

erbridge commented Jun 12, 2020

pezholio commented Jun 3, 2020 •

edited

Loading

pezholio commented Jun 3, 2020 •

edited

Loading