Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: rewrite with mkdocs and add search #363

Open
wants to merge 2 commits into
base: master
Choose a base branch
from

Conversation

hay-kot
Copy link

@hay-kot hay-kot commented Feb 23, 2023

Closes #235

Demo: https://hay-kot.github.io/sprig/

Highlights

  • Removes Jekyll in favor of Material for Mkdocs
  • Adds Search Support
  • Adds auto publishing GH pages on release tag via GH actions
  • Adds README.md for starting the development server for the documentation framework locally.

This PR rewrites the current documentation site from jekyll to Mkdocs with the Material theme. With that comes built in search.

CleanShot 2023-02-22 at 17 32 18

I did not implement this with the existing Jekyll theme because

  1. Adding Search to a Jekyll site looked like a custom implementation which adds more maintenance burden to the project. Robust search support comes for free with Mkdocs Material
  2. Material for Mkdocs has become one of the major default documentation themes, it's used by lots of projects across language eco-systems

The major downside is that you have to use python to run the development server locally, however it's a small trade-off for what you get (IMO)

the Material theme also offers a lot of customizable elements for enhancing the documentation in the future if desired. See the link below for some examples

https://squidfunk.github.io/mkdocs-material/reference/code-blocks/

I'm just using the default theme for now, but I can change the colors to match the existing slate theme if desired. I mostly wanted to get this out there to see if there was any interest in this change

@hay-kot hay-kot changed the title Docs/rewrite with mkdocs docs: rewrite with mkdocs and add search Feb 23, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Add searchable index of functions
1 participant