Stream: cds hooks/committers
Topic: docs / PR #94 Evaluate MkDocs static site generator
Github Notifications (Sep 13 2017 at 05:20):
kpshek opened PR #94
from mkdocs to master
This is a prototype / evaluation of MkDocs, a static site generator (like Slate). This pull request is to test if I can get Heroku review apps to successfully work with MkDocs
Github Notifications (Sep 13 2017 at 05:28):
kpshek synchronized PR #94
Github Notifications (Sep 13 2017 at 05:37):
kpshek synchronized PR #94
Github Notifications (Sep 13 2017 at 05:50):
kpshek synchronized PR #94
Github Notifications (Sep 13 2017 at 05:58):
kpshek synchronized PR #94
Github Notifications (Sep 13 2017 at 06:03):
kpshek synchronized PR #94
Github Notifications (Sep 13 2017 at 06:05):
kpshek synchronized PR #94
Github Notifications (Sep 13 2017 at 06:29):
kpshek synchronized PR #94
Github Notifications (Sep 13 2017 at 06:32):
kpshek synchronized PR #94
Github Notifications (Sep 13 2017 at 06:34):
kpshek synchronized PR #94
Github Notifications (Sep 13 2017 at 06:38):
kpshek synchronized PR #94
Github Notifications (Sep 13 2017 at 06:44):
kpshek synchronized PR #94
Github Notifications (Sep 13 2017 at 06:47):
kpshek synchronized PR #94
Github Notifications (Sep 13 2017 at 06:50):
kpshek synchronized PR #94
Github Notifications (Sep 13 2017 at 06:57):
kpshek synchronized PR #94
Github Notifications (Sep 13 2017 at 19:08):
kpshek edited PR #94
from mkdocs to master
There are several things around Slate that have caused us to evaluate another static site generator.
## Reduce contributor friction
Slate requires Ruby which can be cumbersome to setup and configure for Windows devices. We want to reduce any friction to contribute to the documentation and specification by our diverse community.
## Site theme
Slate's default theme contains a right hand sidebar for code examples which initially seemed great. However, in practice, this has not worked out so well. When the code examples are light, the main content in the middle is unnecessarily constrained (width / real estate wise). When the code examples are large, the alignment between the main content and code examples are awkward. We would rather have the code examples inline with the main content.
Additionally, there is not a community of alternate Slate themes and we have no intention/desire to work on a custom theme to our liking. Thus, we would prefer a static site generator that has a default (or well supported alternate) theme that we like.
## Upgrading the generator
To use Slate, you fork the project repository and start adding your content directly in the repository. To upgrade to newer versions of Slate, you must pull/merge changes from the upstream project into your fork. This is awkward and it pollutes the commit history of our project with the contributions from Slate.
It would be ideal to utilize a static site generator that is a library/tool that can take our own content and produce the site.
After exploring other options, we're evaluating MkDocs as a potential replacement for Slate. What we like about MkDocs so far:
- It is requires Python and installs simply via pip
- Has a great default theme with lots of custom themes to choose from
Github Notifications (Sep 13 2017 at 19:23):
Thanks @kpshek — I agree with the rationale above! I'll just add that with any approach we take, editing content directly within GH by following edit links like this should provide a low-effort way for quick contributions (without local software installations or git clones required).
Github Notifications (Sep 14 2017 at 11:03):
@kpshek I assume you have already evaluated using Jekyll and the standard Github pages approach and found it deficient in some way?
Github Notifications (Sep 14 2017 at 13:55):
@olbrich - Yes, we evaluated Jekyll previously (before we landed on Slate).
The key to using Jekyll is that you need to find (or define) a theme that fits your needs. Given that we would really like to use a theme that has already been built rather than spend time building our own, we were searching for themes to use. We weren't able to find anything that we liked.
As an aside, I'm a big fan of Jekyll and use it for several other projects. One of those projects uses the Github API styling for Jekyll (note that this is not a theme though so there is a bit manual work to get it working).
Jekyll, being Ruby based, shares the same contributor friction that Slate has. Ruby's my go-to language/platform so I'm always happy if I'm doing something in Ruby. But, having spent about an hour total going back and forth with someone on Windows to get Ruby & DevKit installed such that
bundle installwould complete successfully on this repository made me acutely aware of the friction that exists for these contributors.If we go with MkDocs, we will still be hosting the content here via Github Pages since MkDocs simply generates the static content (just like Slate does).
Github Notifications (Oct 02 2017 at 22:11):
isaacvetter assigned PR #94
Github Notifications (Oct 02 2017 at 22:11):
isaacvetter assigned PR #94
Github Notifications (Oct 19 2017 at 21:21):
kpshek synchronized PR #94
Github Notifications (Nov 08 2017 at 16:49):
kpshek synchronized PR #94
Github Notifications (Nov 08 2017 at 16:54):
kpshek synchronized PR #94
Github Notifications (Nov 08 2017 at 16:59):
kpshek synchronized PR #94
Github Notifications (Nov 08 2017 at 17:20):
kpshek synchronized PR #94
Github Notifications (Nov 08 2017 at 17:23):
kpshek synchronized PR #94
Github Notifications (Nov 08 2017 at 17:29):
kpshek synchronized PR #94
Github Notifications (Nov 08 2017 at 20:30):
kpshek synchronized PR #94
Github Notifications (Nov 08 2017 at 20:41):
kpshek synchronized PR #94
Github Notifications (Nov 08 2017 at 21:48):
kpshek synchronized PR #94
Github Notifications (Nov 08 2017 at 22:00):
kpshek synchronized PR #94
Github Notifications (Nov 08 2017 at 23:54):
kpshek synchronized PR #94
Github Notifications (Nov 09 2017 at 00:01):
kpshek synchronized PR #94
Github Notifications (Nov 09 2017 at 01:08):
kpshek synchronized PR #94
Github Notifications (Nov 09 2017 at 03:51):
kpshek synchronized PR #94
Github Notifications (Nov 09 2017 at 04:03):
kpshek synchronized PR #94
Github Notifications (Nov 09 2017 at 04:08):
kpshek synchronized PR #94
Github Notifications (Nov 09 2017 at 04:09):
kpshek review_requested PR #94
Github Notifications (Nov 09 2017 at 04:09):
kpshek review_requested PR #94
Github Notifications (Nov 09 2017 at 04:09):
kpshek review_requested PR #94
Github Notifications (Nov 09 2017 at 04:09):
kpshek unassigned PR #94
Github Notifications (Nov 09 2017 at 06:00):
The theme looks fabulous! And the menus and scrolling-based sections works really nicely too. Only tiny functional gripe is that the code blocks don't have syntax-highlighting. Not that it's a huge deal for JSON anyway.
I didn't review the content, but only the organization and functionality -- and it looks great on that score. Huge usability Improvement, and I think we should go ahead with it!
Github Notifications (Nov 09 2017 at 06:13):
kpshek synchronized PR #94
Github Notifications (Nov 09 2017 at 06:15):
@Josh Mandel - I just added support for code syntax highlighting by simply enabling the recommended Material extensions, one of them being the syntax highlighter. Take another look!
Github Notifications (Nov 09 2017 at 06:20):
Well now what am I supposed to gripe about?!
It looks perfect :-)
Github Notifications (Nov 09 2017 at 14:23):
Is the data model in swagger up-to-date? Wondering if we should keep/remove.
We have the Swagger API in a separate repository (api) right now. However, I want to move the YAML file into this repository and make it part of our site/specification. This will make it easier to keep it up-to-date with any changes we do in the future.
I will do that as soon as this gets merged to master.
Github Notifications (Nov 09 2017 at 19:04):
kpshek closed PR #94
Last updated: Apr 12 2022 at 19:14 UTC
