search

ankitects / anki

Anki's shared backend and web components, and the Qt frontend
https://apps.ankiweb.net
Other
18.31k stars 2.09k forks source link

Fix Docsify issues or investigate alternatives like mdbook #977

Closed dae closed 3 years ago

dae commented 4 years ago

Docsify has an annoying bug where sidebar clicks will not scroll:

https://anki.tenderapp.com/discussions/beta-testing/1852-anki-docs-search-button-anchors-are-not-working-ie-jumping

Even if we're able to fix that issue, links to subsections near the end of a page aren't ideal - since the page can't scroll past the bottom, the section that we want the user to read may appear near the bottom of the window, requiring the user to skip their eyes over a number of sections above. To address that we'd need to pad out the bottom of each section as well.

It may be worth considering alternatives like mdbook instead. Mdbook positives:

Downsides:

NicoleRauch commented 4 years ago

I noticed two more issues other than the non-scrolling text:

It would be nice if the search term could be highlighted in the documentation as well (it only gets highlighted in the results in the result list, but not in the actual documentation). That would make it much easier to find the right spot. (This might also help mitigate the above issue with not being able to scroll far enough, because the relevant section is clearly marked.)

Also, the result texts don't seem to evaluate markdown? (e.g. if you search for "order" you find an entry in the section "New Cards" which displays "...nally. **order** controls whether Anki should add ne..." as the result text, while the documentation itself shows "order" in boldface.

dae commented 4 years ago

Experimenting with mdbook on https://faqs.ankiweb.net/

andrewsanchez commented 4 years ago

I'd be interested in helping out with this. I can help with the deployment as well. I'm also interested in helping improve documentation in general. Would you be open to using https://readthedocs.org/ or the super cool https://jupyterbook.org?

dae commented 4 years ago

Readthedocs is a hosting service more than a document processor, isn't it? What makes you recommend it? Sphinx is more appropriate for API docs than an end-user manual, and I'd rather have the Anki manual served on a place that doesn't serve ads.

Jupyterbook seems to suffer from the same issue as docsify, where a link to a section on a page results in a wall of text without a clear indication of where the user should be looking - unless you read the anchor in the URL, you can't tell which section you're supposed to be looking at, eg: https://jupyterbook.org/content/myst.html#tools-for-writing-myst-markdown. mdbook highlights it to make it more obvious, eg: https://faqs.ankiweb.net/#anki-desktop-the-computer-version-and-ankiweb

Jupyterbook's print to pdf function also suffers from the same issue as docsify, where it can only print one section - mdbook can produce a pdf of the entire book at once, which some people prefer.

And finally, its search functionality seems a lot slower than either docsify or mdbook.

Are there some killer features it offers that we'd be missing out on?

The main downside of mdbook is we don't get free TOCs in the left sidebar - each entry on the left needs to be manually added and linked to the relevant page. There's a script that will place a TOC of subheadings at the top of the document on the right, but if we wanted all the subheadings to be listed on the left, we'd need to split them up into multiple files and link each subheading separately, which is too cumbersome - so we'd probably need to go with the subheadings on the right if we migrated the manual to mdbook.

andrewsanchez commented 4 years ago

Ok, interesting. I don't think I fully grasped the entirety of the problems you wanted to address. Let me look into this in more detail and I will get back to you. Thanks for clarifying!

dae commented 3 years ago

If a compelling other option doesn't present itself, I think we'll eventually need to bite the bullet and switch over to mdbook. Aside from the issues mentioned above, one other issue with docsify is that it's rendering the markdown client-side, which can make manual content difficult to locate from Google.

johan456789 commented 3 years ago

How about MkDocs and Docusaurus? Both are pretty and use horizontal space more efficiently by showing sections on left sidebar and table of contents on right sidebar, unlike Docsify and mdBook.

MkDocs with Material theme

Example1, Example2 (this layout suits Anki manual better)

Quick and dirty proof of concepts (took me <30min) : https://johan456789.github.io/anki-mkdocs/intro/

Pros

Cons

Docusaurus v2 is also worth checking out. It has a lot of features but may be too complex for our purpose. ## [Docusaurus v2](https://v2.docusaurus.io/) [Example](https://v2.docusaurus.io/docs/) ### Pros - Future-proof - Built by Facebook and used in React docs, unlikely to suddenly go away - Document versioning - i18n (coming soon, this will be more ideal than the current community hosted way) - SEO friendly - More advanced search powered by DocSearch [for free](https://docsearch.algolia.com/docs/faq/#how-much-does-it-cost), avoids ["colour search" problem](https://github.com/ankitects/anki-manual/pull/38#issuecomment-734960508) - Dark mode - Highly extensible using React and plugins ### Cons - Might be overkill for Anki (complex to set up? → I haven't tried) - Introduce other techs (JavaScript and React) - Privacy concerns with Algolia (DocSearch) Analytics - v2 is still alpha (since mid-2019) but already quite stable (their claim)
andrewsanchez commented 3 years ago

I actually can't reproduce the scrolling issue consistently. The first time I tested it, I confirmed the reported misbehavior. On subsequent attempts, scrolling has been working just fine.

GitLab's Handbooks are really nice.

since the page can't scroll past the bottom, the section that we want the user to read may appear near the bottom of the window, requiring the user to skip their eyes over a number of sections above.

Perhaps a bit hacky, but one workaround might be to add a lengthy footer at the bottom of the page. If you go to the handbook linked above and click the last item in the ToC on the right, "Contribute your lessons," you can see how having the footer allows the scrolling to focus an item at the end of the doc.

MyST markdown and its usage with Spinx directives is the killer feature of Jupyter Book. Not sure how relevant it is for Anki's docs though. One use case I've fantasized about is to write a Sphinx role that would allow authors to annotate their plain text documents with inline cloze deletions, enabling the generation of a .apkg as a result of the doc building process. This would also facilitate defining some syntax conventions around writing free form markdown notes and generating Anki cards from them. For example, you can imagine a prettier way to denote cloze deletions in MyST:

{clz}`Example of an [inline role](1) that can be used to generate [cloze deletion cards](2).`

I will add that Jupyter Book is under super active development by an ambitious team of extremely innovative thinkers who are eager to develop some of the best documentation tools in the space of open science. I've contributed to Jupyter Book's CLI and I'm guessing they'd be open to supporting such enhancements.

dae commented 3 years ago

Thank you both for the suggestions, and for doing a quick version of the manual which was informative.

mkdocs looks good, but I am concerned by things like searching features and language selection being limited to insiders, as they ask insiders not to share the code with others. It complicates things if people can't easily fork and rebuild the docs repo themselves. Apart from that it seems to be at a similar level of functionality and a bit prettier in some ways than mdbook, though I do slightly prefer the search output from mdbook, and the way you can click anywhere in a title to get a link to it, and get that area highlighted.

Andrew, I agree that cloze functionality is probably not useful for the manual :-) I had a quick poke about with GitLab - I can see it has "on this page" on the right, but doesn't appear to have a TOC for major sections - do you have a link to something that looks more similar to Anki's manual?

Jupyter Book looks fancy, but I'm not sure we need all that.

dae commented 3 years ago

I migrated AnkiMobile's manual over to mdbook a few days ago. The links to separate sections had to be manually updated which was a pain - while there's a link checker available for external links, it doesn't understand #anchor links. Happy with the faster page load speeds and the fact that the interface responds nicely on phones (and even follows the set dark mode). There were some out-of-date sections that needed updating at the same time, so it took longer than expected.

While there is a TOC generator that can embed a TOC at the top of right section, I opted for unrolling the nested sections into separate top-level sections for AnkiMobile. Anki's manual is larger and that probably won't be practical, so if migrating it, we may need to either put the TOC on the top right of each section, or start splitting the files up and linking subsections in the left outline. The former is much easier than the latter, so would probably be the best way to start, as we could gradually migrate to the latter if appropriate.

We're currently using https://github.com/peaceiris/actions-mdbook to build the pages, but that does not appear to support anything except the base mdbook, so we'd need to write our own action, or I'd need to set up Buildkite to build the manual with mdbook-toc installed.

dae commented 3 years ago

Forgot to close this; the manual has subsequently been migrated to mdbook.