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!
Top comments (12)
I'd also suggest Netlify. Azure Strorage has no free tier which is a bit of a turn off for me. (I only know of this because it impacts Azure Functions. It's a super minor cost, but still bugs me a bit. ;)
How much did your pricing look like with azure storage? It appears to be a few pennies for what I am looking at. (which i get is not free, but i am curious what you found)
I want to say roughly 60 cents a month. Which to be fair is incredibly cheap, but when it comes to building quick demo sites, I don't want to have to start thinking about that stacking up over time. I'm really surprised Microsoft doesn't just have a free tier for super small, low usage sites like your docs, demos, etc. The fact that I can deploy a site for a conference presentation or blog post, whatever, to Netlify and just not worry about it makes me much more inclined to use it to host stuff.
Thanks for the feedback. It would be nice to have a free option here - and yes, there are credits with the free azure trial, but seems like you would want (and i can see it too) an option for a free hosted site.
Especially, static sites. 😅
John, as an alternative you can also use some popular documentation site generator such as docsify.js, docsie. They are purely markdown based and can be hosted via GitHub pages. I have been using docsify.js via GitHub pages since months now.
Thanks. I tried gatsby before and its good. VuePreas is creates for a similar purpose - but using Vue.
Interesting! Thanks for sharing.
GitHub pages is good for free hosting.
I just switched from GitHub pages to Netlify and I'm really liking it!
Have you checked out forestry.io/ ?
I love keeping everything in Markdown and images in Cloudinary!
I just wrote a bit about why