[FEAT] Move away from Gitbooks theme to implement search

[strugee]

Objective

It should be easy to search the docs for search terms.

Initial Implementation Requirements

search plugin is enabled. This is complicated to do - see below.

Other Considerations

I looked into doing this myself since it seemed like a pretty simple PR. But it's not. mkdocs comes with a built-in search plugin, but enabling it throws this error in the JavaScript console:

Uncaught ReferenceError: base_url is not defined
<anonymous> http://127.0.0.1:8000/neon-docs/search/main.js:106

The search box also does not do anything. If I comment out the theme configuration and use the default mkdocs theme, the search box works fine. This appears to be because this additional snippet of JavaScript is inserted into the page just before the search plugin JS is loaded:

        <script>
            var base_url = ".",
                shortcuts = {"help": 191, "next": 78, "previous": 80, "search": 83};
        </script>

Because of this, I looked into inserting custom content into the theme, but it does not look particularly extensible. It also does not appear to support extra_javascript which is documented by mkdocs. Finally, the GitbookIO/theme-default repo is archived since 2020.

I would suggest moving to a different theme. mkdocs Material seems to be mentioned a lot, or there's some others listed on https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes.

[strugee]

I would suggest moving to a different theme. mkdocs Material seems to be mentioned a lot, or there's some others listed on https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes.

I also almost said "I quite like the ReadTheDocs theme too", but that begets the question - why not just straight up move to ReadTheDocs entirely? It's got a number of goodies (including search) compared to the current setup and would allow killing the .github directory in this repo entirely.

[NeonDaniel]

We could use the RTD theme; I believe the reasons I moved away were:

• The nested items in the side bar wouldn't expand/collapse as expected
• Some of the Mycroft docs included here had specific formatting for GitBook

[NeonClary]

@strugee Can you see anything helpful from what Mycroft is using for their docs? They have search, and also the nested items running perfectly.

[NeonDaniel]

@strugee Can you see anything helpful from what Mycroft is using for their docs? They have search, and also the nested items running perfectly.

Mycroft is using GitBook (a paid service), so the rendering is a little different from what we get with mkdocs. We won't have any updates to sync back from Mycroft at this point, so we can also just take the time to remove any Gitbook-spcific formatting and organize these around a different theme.

[NeonDaniel]

For reference, the theme is defined in mkdocs.yml: https://github.com/NeonGeckoCom/neon-docs/blob/535c66b0e05c244fb4aa7974d5c319e9ae7272a5/mkdocs.yml#L4-L7

[H-Ashcraft]

Hey, commenting so I can help out.

[strugee]

@strugee Can you see anything helpful from what Mycroft is using for their docs? They have search, and also the nested items running perfectly.

Oops, sorry for missing this! Guess Daniel answered for me.

[H-Ashcraft]

I messed with this for a few hours and came to the same conclusion as strugee. This website: https://pawamoy.github.io/mkdocs-gallery/themes/gitbook/ allows you to try different MkDocs themes out live and their Gitbook theme search is generating the same error mentioned above. As far as the Gitbook specific formatting and nested items in the sidebar go, I'm happy to test alternative themes and try to get the same results before ditching the Gitbook theme. Let me know what you think.

[strugee]

Surprisingly on paper Neon may also qualify for the GitBooks OSS offering: https://docs.gitbook.com/account-management/plans/apply-for-the-non-profit-open-source-plan

Doesn't mean they won't exercise their discretion and disqualify Neon as a for-profit project though.

[NeonDaniel]

Surprisingly on paper Neon may also qualify for the GitBooks OSS offering: https://docs.gitbook.com/account-management/plans/apply-for-the-non-profit-open-source-plan

Doesn't mean they won't exercise their discretion and disqualify Neon as a for-profit project though.

I'd personally prefer sticking with mkdocs or another open source solution in any case so we can maintain better control of how are docs are published.

As far as the Gitbook specific formatting and nested items in the sidebar go, I'm happy to test alternative themes and try to get the same results before ditching the Gitbook theme. Let me know what you think.

Personally, I am satisfied as long as the nested pages render properly in some navigation menu (I like the side-bar Gitbook and mkdocs themes use, mkdocs just had issues with nested pages last I checked). @mikejgray put the most work into porting skill docs from Mycroft and may have an opinion too.

I'm happy with the way those docs look now, but wouldn't be opposed to refactoring out the Gitbook-specific content into pure Markdown that works with another theme

[strugee]

I'd personally prefer sticking with mkdocs or another open source solution in any case so we can maintain better control of how are docs are published.

Same, just figured I would mention it for completeness.