Not Too Bad for an Hour's Time

#javascript #vscode #vue #webdev

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 (11)

Raymond Camden • Aug 5 '19

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. ;)

John Papa • Aug 5 '19

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)

Raymond Camden • Aug 5 '19

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.

John Papa • Aug 5 '19

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.

Yashu Mittal • Aug 15 '19

but seems like you would want (and i can see it too) an option for a free hosted site.

Especially, static sites. 😅

Idris Rampurawala • Aug 5 '19

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.