Update documentation to restore GitHub Pages functionality #387
Conversation
Liquid Exception: Liquid syntax error (line 39): Variable '{{substring 'A full quote' -5 5}' was not properly terminated with regexp: /\}\}/ in template.md
This reverts commit a864ed9.
|
It looks really good. Thank you for your work! I have some small tweaks, and a question or two, but thank you so much for this :) |
There was a problem hiding this comment.
- the README should still exist in the root of the repo, so that GitHub shows it
- I'm fine with all pages, other than the README page, being prefixed with
/docs/in the URL
- I'm fine with all pages, other than the README page, being prefixed with
- Is there a way to do versioning?
- I'm not convinced that
mainshould be the only available documentation, which may change between releases, and thus give incorrect info to users of the latest version - it would be nice, if we had multiple versions of the docs available, based on the release tag, but if only the latest release is available, so be it
- I'm not convinced that
I'll add additional comments here and push updates to this branch once I've made progress on these two items. |
|
I was unable to find any nice Jekyll themes that handled versioned documentation well. We could roll our own solution with an existing theme and have every release as a subdirectory that you can navigate to in the sidebar, but that would make using any search functionality confusing. MkDocs is a very popular SSG for project documentation these days, and it seems to support project documentation a little better than Jekyll does. The Material for MkDocs theme integrates well with a document versioning tool called mike. At first glance, it looks like it would provide a nice workflow. Example versioned docs with that theme: https://squidfunk.github.io/mkdocs-material-example-versioning/0.1/ |
|
The original solution will suffice, unless of course, you'd like to try to get versioning working. |
|
If you're open to it, I'll happily take on a MkDocs refactor to get us versioned docs. However, that is outside the scope of this PR. I have started work on fixing up the current GitHub Pages docs without moving the README around as we discussed. I will tag you here once it's ready for another review! |
|
Hello @mcDevnagh - I have pushed a few more changes. A deployment of the latest commit is live at https://docs.huggins.io/zk/. The README is back in the repository root, as requested. |
|
looks good. thank you kindly for your work here! |
|
Happy to help! Thank you for working with me on these changes. Love this project and glad to be a (small) part of it. |
|
idk if this is still being worked on but https://docs.huggins.io/zk/ returns nothing. where should i be looking? |
|
The documentation is at https://zk-org.github.io/zk/. I used my domain during development because I cannot make deployments in |
oh nice. but is there any plan to implement some sort of search feature to the docs at all? or a table of contents to make scrolling around easier? some sort of way to source the /docs folder instead of having to do everything through the repo would be nice. |
This PR fixes the documentation site deployed to GitHub Pages, as pointed out in #386. You can view the site created from these changes at https://docs.huggins.io/zk/.
The easiest way to get the site working again was to move README.md to the
docs/folder. This moves it out of the repository root, but it's still one of the standard README locations checked by GitHub - the README will still render at the bottom of the repository homepage. If we aren't okay with that move, I will explore making additional changes to the Pages deployment action so that we can leave the README where it is now.To support this change, I have:
fix/gh-pagesbranch.Any and all feedback is appreciated. Thanks!
Closes #386.