loading...
Cover image for Not Too Bad for an Hour's Time
Microsoft Azure

Not Too Bad for an Hour's Time

john_papa profile image John Papa Ńâ╗2 min read

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!

Discussion

pic
Editor guide
Collapse
mattwaler profile image
Matt Waler

Try out hosting on Netlify!

Collapse
darkes profile image
Victor Darkes

I just switched from GitHub pages to Netlify and I'm really liking it!

Collapse
raymondcamden profile image
Raymond Camden

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

Collapse
john_papa profile image
John Papa Author

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)

Collapse
raymondcamden profile image
Raymond Camden

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.

Thread Thread
john_papa profile image
John Papa Author

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.

Thread Thread
mittalyashu profile image
Yashu Mittal

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

Especially, static sites. ­čśů

Collapse
idrisrampurawala profile image
Idris Rampurawala

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.

Collapse
john_papa profile image
John Papa Author

Thanks. I tried gatsby before and its good. VuePreas is creates for a similar purpose - but using Vue.

Collapse
ruslangonzalez profile image
Ruslán González

Interesting! Thanks for sharing.

Collapse
darkes profile image
Victor Darkes

GitHub pages is good for free hosting.

Collapse
ajonp profile image
Alex Patterson

Have you checked out forestry.io/ ?

I love keeping everything in Markdown and images in Cloudinary!
I just wrote a bit about why
ajonp.com/blog/cloudinary-in-jamst...