Implement style guide menu in Joplin (make styleguide iframe TOC match Gitbooks TOC)

[desigonz]

As a content editor I want the style guide panel in Joplin to display information relevant to the component/content type I am editing so that I can more efficiently find appropriate guidance.

Is your feature request related to a problem? Please describe. The style guide panel in Joplin allows content editors to reference the style guide, but it's only half-way set up.

• Gitbook syncs to the Github repo. Gitbooks should be the source of truth where editors go to update the style guide.
• Joplin pulls from the Github repo.
• We haven't yet implemented it so that the menu syncs with Gitbooks. That's been confusing because when we navigate the style guide in Joplin, we see old content that doesn't match with Gitbooks.
• Since the Gitbook to Github sync is set up, we don't need to migrate info and department pages (#2985), we just need to fix the menu thing.
• Style guide content in Joplin
  • Currently, you see the correct style guide content on Joplin for information and service pages.
  • Department page style content isn't appearing in Joplin—it 404s (see screenshot)

Acceptance criteria

• [x] For content types that don't have a page in the style guide yet, the default open page should be the Gitbook intro page
• [x] When a user opens the menu in the Joplin style guide tab, the menu should match the menu on Gitbooks (note: currently it's feeding in the old Github content menu, which does not match Gitbooks)
  • [x] TBD interaction for the dropdown menus like "Pick the perfect page type"—dev team, what would be easiest to implement for MVP?
    
• [ ] Once this is implemented, let's get rid of the _words folder contents in Github. It's been confusing for the content team—in the past we've been updating in both places, but our source of truth from now on will be the Gitbook.

[desigonz]

@briaguya Wasn't planning to work Jekyll build process, and it's much lower priority than other things. Is that a blocker for this issue? We could discuss this at the next dev sync if you'd like.

[easherma]

@desigonz are we going to try to rethink our jekyll build process (the way the github.io version of the style guide) is done for this?

From what I've seen the github/gitbooks integration we have going on is kind of messy, and it might be worth thinking through a more manageable solution.

Possible options:

• Try to figure out a way to make gitbooks and iframes play nice (probably asking gitbooks nicely to see if they're willing to help us with cross frame options)
• Update our jekyll theme to display the correct items in the side menu but nothing else
• Rethink our style guild build process/jekyll theme stuff

@briaguya for the record:

• gitbooks doesn't allow iframes
• i looked into other styleguide management options, including a plugin for Wagtail that exists exactly for that purpose
• however, content team still wants the Gitbook as a standalone version that can be a way to easily share best practices outside of the alpha project.
• therefore, here we are :-)

[easherma]

Brain dump: I've tried a couple things, but Jekyll isn't really set up to be nimble about parsing the data from SUMMARY.md as I'd like.

I'm tempted to migrate this to a Hugo project, which will follow the directory structure and link everything with relative links no problemo. Generating the Table of Contents is something it can do automatically, but the file structure isn't quite the same as Gitbook's.

I'm going to stew on this. It's not ideal, but hardcoding the table of contents in HTML might not be too bad, since we don't change it terribly often.

Other options: Try Gitbooks legacy CLI. It's not supported anymore and may be missing some features, but it may work just fine for the iframe. Look into a tool for parsing the markdown generated by Gitbooks into html or some other template (main issue here is the filepaths and then having a directory that matches)

[easherma]

I made a version with a hard-coded nav for table of contents, its visibile in joplin now, or at https://cityofaustin.github.io/digital-services-style-guide/

[desigonz]

Looks great, QA complete! 🎉 I guess we can close the issue?