search

squidfunk / mkdocs-material

Documentation that simply works
https://squidfunk.github.io/mkdocs-material/
MIT License
20.12k stars 3.47k forks source link

How to search a single language translation #867

Closed maurelian closed 6 years ago

maurelian commented 6 years ago

Description

Our documentation site recently had a full translation of Korean submitted. This is obviously wonderful.

Unfortunately, the search functionality mixes the two languages, which reduces the usability for readers in either language. Adding more languages in this way would presumably make it worse.

image

Expected behavior

I would prefer if there was a site wide toggle for the active language. Does such an option exist?

Package versions

python==3.6 mkdocs==0.17.2 mkdocs-material==2.2.5

Project configuration

https://github.com/ConsenSys/smart-contract-best-practices/blob/master/mkdocs.yml

Thanks very much for this excellent project, and for your help in advance!

squidfunk commented 6 years ago

MkDocs doesn't support language toggling/branching, so Material cannot add this functionality either. To solve this, you would need to build two separate versions of your docs, one for each language configuring the correct search language in mkdocs.yml. By customizing the theme you could link to the other language inside the header or where you want, effectively switching between the two separate builds.

maurelian commented 6 years ago

Great explanation, thank you!

rllola commented 5 years ago

@squidfunk I have been following your recommendation and done it for ZeroNet documentation. The most tricky part was the lunr search_index.json file which was containing the text. Also for convenient I wanted to have the 2 languages folders in the docs (so we don't need to modify twice and forget).

Here what I have which I believe might be useful for people willing to do it in the future : https://github.com/rllola/Documentation/tree/french

It has :

Your feedback would be appreciated.

EDIT: the all is still really hacky but it does the job.

squidfunk commented 5 years ago

@rllola Thanks for sharing your setup! It will be beneficial for anyone wanting to achieve this until MkDocs adds support for multi-language builds (if ever).

EDIT: The ZeroNet documentation looks super awesome (I like the logo/color combination). Great to see that people use the customization options Material offers.

maurelian commented 5 years ago

@rllola Have you got a site up with both the french and english versions? I couldn't find one.

rllola commented 5 years ago

@maurelian Sure. https://zeronet.io/docs-dev/en/

I am not done with the french translation tho. I have been focusing on the multi-language support side of it.

Here the PR with a little bit more information : https://github.com/HelloZeroNet/Documentation/pull/117

Let me know if you have questions or need help.

squidfunk commented 5 years ago

Hmm, thinking about it, maybe we could add something like this to Material by default. If somebody can come up with a good spec on how to integrate it in a way that is easily workable, I'm happy to help integrating it or pull it of my self. Here are some problems to tackle:

rllola commented 5 years ago

Also the tricky part is loading the proper search index for lunr. Because by default it is looking in /search/ folder but I generated one for each language and put it inside their respective language folder : /fr and /en. And I need to play with nginx rule to load the proper one which is really hacky.

I believe the others problems that you mentioned are solvable, except maybe the metadata extension (I am not sure what is it :smile: ). For mobile, it needs a little bit more coding but nothing too hardcore.

I would be happy to contribute and start on a PR...

EDIT: Also doing a PR so mkdocs can ignore files would be really neat.

suricactus commented 10 months ago

Would be interesting if someone found a better solution than building a seperate site and search index for each language and share it here.

squidfunk commented 10 months ago

There's the mkdocs-static-i18n plugin which allows for building a single site and index, as I understand. I'm not a user of it, since this comes with some other caveats, which is why we're following the approach to build multiple sites alongside each other and will add better support for this in the future with the new projects plugin, but it might be something to consider.

alexvoss commented 10 months ago

I think a separate search index is a good thing because the size of a single search index would blow up with each translation added.

The projects plugin feels like the right path to me. I have recently started helping @squidfunk develop more examples for Material for MkDocs functionality, which means I am a heavy user of this plugin. One thing I like about the approach taken with it is that it will facilitate more use cases. (I am looking to develop an example that produces a second, stripped-down version of a site -e.g., for including training material in Open edX).