The Vanilla team needed to solve two issues which have been paining the development of Vanilla Framework for some time.
Firstly we needed to improve our workflow for testing and QAing components on our local machines. Up until now, we have been using
npm link on our local branches of Vanilla with our local website branch, then reviewing the examples in the components page of the documentation. This caused a lot of extra overhead to reviewing Vanilla.
Secondly, since we actually build the docs.vanillaframework.io site using the Documentation theme (vanilla-docs-theme), the Vanilla pattern examples we ended up reviewing were no longer purely styled by Vanilla Framework, but as they were extended by the theme.
To solve both these issues, we decided to decouple the examples from the documentation. This change allowed us to move the coded examples of the patterns into a separate “examples” directory of the codebase and remove the hard-coded examples from the documentation.
As the examples were a part of the Vanilla Framework code we simply linked each example page with the Vanilla built from the same branch. This means all examples are only styled by Vanilla and nothing else.
Another benefit that came from this change was that now we have an easy way to find an example of a pattern when reviewing or QAing a pull request. Whereas previously we had to do the
npm link dance. Now we simply check out the branch and run the internal Jekyll site to build Vanilla giving us a directory of pattern pages.
Examples in the docs
So we were happy with these changes: we had solved the issues at hand and were ready to head off and have a celebratory coffee. But, we couldn’t leave the documentation without examples and code snippets.
To solve this issue, we used an embedding paradigm like on Codepen.
We were still lacking the code snippets, so we made the script also pull the HTML source of the linked page into the example, then display the contents of the body in a code block appended after the iframe.
And that was it. The solution gives us:
- A single place for example code
- Examples only displayed using Vanilla
- A local testing environment
- Documentation examples that are automatically up to date
We named this mini project example-js. Please feel free to fork it, use it or file any issues you may find.