search

cityofaustin / ctm-dev-workflow

[Draft] Guides & best practices for application development at CoA
1 stars 0 forks source link

Turn docs into stand-alone site with a useful nav structure #27

Open mattlangan opened 7 years ago

mattlangan commented 7 years ago

GH Pages themes are nice but have 2 limitations that I think require us to find a different solution:

  1. The default supported Jekyll themes don't have any nav structure
  2. CoA docs/guidelines belong on a city-controlled domain, not on a GitHub.io subdomain.

Installing and configuring a Jekyll theme is easy. I've already done it using the prototype Zilker theme that Jake scaffolded a couple of months ago, and deployed as a static site via Now. The real trick is identifying a hosting and DNS scheme that allows us more flexibility than what we currently have with AustinTexas.gov.

@amenity is running into the same issues I am with this stuff so we're trying to identify the right person to talk to about DNS policy, subdomains, and cloud hosting.

MireyaGalarza commented 7 years ago

@mattlangan "identify the right person" will this person be someone at CoA? or just someone with the skills and experience?

mattlangan commented 7 years ago

@MireyaGalarza someone at CoA who oversees DNS

mattlangan commented 7 years ago

Per a recent meeting with Heath Taylor, Alix Holbrook, and Jason Taylor, I might be able to set up guides.austintexas.gov with a /web-development sub-directory in the next few weeks. More to come.

mattlangan commented 7 years ago

The main issue I've hit is limitations on jekyll theme compatibility. See Jake's note on his Zilker commit making it a gem

For example, I've implemented the Zilker theme on the Microservices Guide I'm working on. Here is how it looks published on GH pages (VPN connection required).

Here it is on Now, published as a static site outside of GH-Pages the theme renders properly.

From a broader perspective, I think it also makes sense to build up more competency around AWS S3 hosting since that will be more applicable to CoA web devs' hosting needs and will be part of the city's migration off of on-prem services.

mattlangan commented 7 years ago

In case you can't see the on-prem GH Page, it just renders the markdown as html without any of the theme styling or layout applied.