Peacock has grown quite a bit in the past few months. So much, in fact, that the docs in the README.md are getting long and difficult to navigate.
I decided that I'd explore a static site generator that I could use to display the docs and make them easier to consume for y'all.
Here are the key aspects I'm aiming for:
- minimal changes to existing markdown
- migrate all images
- add additional links for contributions, changelog, and other useful items
- separate from peacock code, in a docs folder
- host in the cloud at a custom domain
- SEO friendly
- remove old markdown
- Keep the original README and decide what should remain there and what should link to docs
- Maintain code and other markdown styling
- Customize theming
I decided this was a great opportunity to try VuePress.
Uh oh, I have never used VuePress before! So I went to the VuePress docs and started hacking away. An hour later, here is where I landed.
More to come still, but I'm thrilled that I can do all of this and not write any Vue/React/Angular code! I love those tools, and I also love that Vue is at the heart of VuePress. Why? Because this means when I need to do something custom, i can drop into Vue components. But for simply taking my markdown and making it into a docs site, it's far simpler. Not Vue knowledge required!
I'll write more on this later, but I wanted to share how quickly I was able to move forward with VuePress. If you have been considering a tool for docs, definitely give this a try.
When it is time to host it, I may consider Azure Storage or GitHub pages. Not quite ready to host it, but I'm thrilled I can think that far ahead already 😊
Thanks to Chris Noring for pairing with me!