Questions about folder structure

hhslepicka commented 1 year ago

Hi,

I am currently using mkdocs-static-i18n for my documentation, which works great with the suffix approach. Now I need to expand the number of languages supported, and the suffix approach is getting out of hand for me.

I tried to switch from the suffix to the folder approach following the instructions on the README file, and I am having some difficulties.

I understand that the folder structure is more strict than the suffix approach but I would like to know if I am making mistakes or if it is behaving how it should.

Questions

404 Error for pages not translated

I noticed that with the folder structure, if I don't have a page translated for all the languages, when I use the language switch (mkdocs-material enabled or disabled) it gives me a 404 error page.

Warning for relative paths

I am also noticing some warning messages related to the use of relative paths on the nav section:

WARNING  -  A relative path to 'cli/machine-new.md' is included in the 'nav' configuration, which is not found in the documentation files

Support for `navigation.indexes`

With the folder structure, I also noticed the navigation.indexes feature from MkDocs Materials is no longer working, and the option seems to be ignored.

mkdocs.yml

Here is part of my mkdocs.yml configuration:

Configuration

``` docs_dir: 'site/content' plugins: - swagger-ui-tag - mkdocs-video - search - i18n: default_language: en docs_structure: folder # to speed up development build uncomment the line below # default_language_only: true languages: en: name: English build: true site_name: Documentation pt: name: Português build: true site_name: Documentação material_alternate: true nav: - Home: index.md - Documentation: - ... - CLI: - cli/index.md - Commands: - bot: - bot deploy: cli/bot-deploy.md - bot update: cli/bot-update.md - bot release: cli/bot-release.md - bot list: cli/bot-list.md - machine: - machine new: cli/machine-new.md - machine status: cli/machine-status.md - machine remove: cli/machine-remove.md - machine log: cli/machine-log.md - machine screen: cli/machine-screen.md - task: - task create: cli/task-create.md - task restart: cli/task-restart.md - task finish: cli/task-finish.md - task cancel: cli/task-cancel.md - activity: - activity set: cli/activity-set.md - activity list: cli/activity-list.md - log: - log create: cli/log-create.md - log delete: cli/log-delete.md - log download: cli/log-download.md - log read: cli/log-read.md ```

New project structure

And the project folder structure is as follows:

``` . ├── README.md ├── mkdocs.yml ├── requirements.txt └── site ├── content │ ├── assets │ │ ├── favicon.png │ │ ├── images │ │ │ ├── ... │ ├── en │ │ ├── cli │ │ │ ├── index.md │ │ │ ├── machine-log.md │ │ │ ├── machine-new.md │ │ │ ├── machine-remove.md │ │ │ ├── machine-screen.md │ │ │ ├── machine-status.md │ │ ├── index.md │ ├── pt │ │ ├── cli │ │ │ ├── machine-new.md │ │ │ └── machine-remove.md │ │ └── index.md │ └── stylesheets │ └── extra.css └── overrides └── layouts ├── home.html └── home.pt.html ```

Thank you for this great project and the help. I can try to work on a mock project to reproduce the issues that I mentioned above if that helps.

ultrabug commented 1 year ago

hello @hhslepicka

Thanks for your kind words, I'm happy to hear that this project is helping you!

Do you have a public repo I can try your layout with?

Please provide something concrete that I can reproduce the behavior you're seeing

The folder structure is indeed harder to work with

hhslepicka commented 1 year ago

@ultrabug I apologize for my late reply. I got caught up with some deadlines over the last week. Here is the repository that will demonstrate my questions from issue: https://github.com/hhslepicka/mkdocs-i18n-folder-issue

Repository Organization

There are two branches in the repository:

main: this is the code using the folder structure
suffix: this is the code using the suffix structure

The example

To demonstrate the issues above, this small example uses only two languages. The English language pages are complete, but we are missing, on purpose, the machine remove page for the Portuguese language.

Steps to reproduce

Install the dependencies from requirements.txt

Using the main branch, do:

mkdocs serve

INFO     -  Building documentation...
INFO     -  Cleaning site directory
WARNING  -  could not find 'pt' alternate for the default version of page 'en/cli/machine-remove.md'
WARNING  -  A relative path to 'cli/machine-remove.md' is included in the 'nav' configuration, which is not found in the documentation files
INFO     -  Translated navigation to pt
INFO     -  Building en documentation
INFO     -  Building pt documentation
INFO     -  Documentation built in 0.33 seconds
INFO     -  [19:50:41] Watching paths for changes: 'site/content', 'mkdocs.yml'
INFO     -  [19:50:41] Serving on http://127.0.0.1:8000/

notice the warnings produced as described above
open the URL
navigate the English language site. Everything should look ok except for the Command Line Interface page, that should not be a separate page but be linked to the CLI menu item (see image below [1]).
switch languages and click at Commands > machine > machine remove
a 404 error page will be displayed, and the URL will look like this http://127.0.0.1:8000/cli/machine-remove.md demonstrating the other question above.

Switch to the suffix branch and repeat the same steps as above
- No warnings will be displayed
- The CLI menu will display the Command Line Interface page
- Switching languages and trying to open the Commands > machine > machine remove will display the English version of the page as an expected fallback for content not yet translated.

[1] Command Line Interface menu item (navigation.indexes)

Thank you for your time and for looking into it. I will also try to debug on my side and report back if I find anything.

ultrabug commented 1 year ago

Hi @hhslepicka

Thanks for your helpful demo site structure.

I can already tell you that the problem comes from the fact that you're using static navigation configuration which in turn creates a Link object to a file that is indeed not present on the pt language... hence the 404.

That being said, I'll have to think of a possible way to make this plugin detect and fix that for you ...

There are so many combinations it's hard to cover them all :(

hhslepicka commented 1 year ago

@ultrabug thank you for looking into that.

hhslepicka commented 1 year ago

What would be an alternative to static navigation?

ultrabug commented 1 year ago

Well, let the dynamic navigation reflect your folder structure

ultrabug commented 1 year ago

That being said, I have a prototype branch that fixes the problem... I'll have to give more thoughts to it

hhslepicka commented 1 year ago

@ultrabug do you have news on this issue? Is there anything I can do to help? I would be glad to test the branch with the possible fix.

ultrabug commented 1 year ago

I just pushed my local stash in the #187 PR which is still WIP but should be able to demonstrate the fix @hhslepicka

Please test it and tell me how it feels

hhslepicka commented 1 year ago

@ultrabug thank you for pushing the changes. I was able to test it here locally and the 404 errors are gone and the warnings are as well. From my test, the navigation.indexes are still being ignored with the new branch.

Another thing that I noticed while building my real project documentation was that internal page links are now issuing warnings. I updated the issue demo project to reflect that.

Here is my output with the updated code:

mkdocs build
INFO     -  Cleaning site directory
INFO     -  Building documentation to directory: /Users/slepicka/sandbox/git-slepicka/mkdocs-i18n-folder-issue/docs
[PosixPath('index.md'), PosixPath('.'), PosixPath('en/index.md'), PosixPath('en/index.md')]
[PosixPath('cli/index.md'), PosixPath('index.md'), PosixPath('en/cli/index.md'), PosixPath('en/cli/index.md')]
[PosixPath('cli/machine-new.md'), PosixPath('machine-new.md'), PosixPath('en/cli/machine-new.md'), PosixPath('en/cli/machine-new.md')]
[PosixPath('cli/machine-remove.md'), PosixPath('machine-remove.md'), PosixPath('en/cli/machine-remove.md'), PosixPath('en/cli/machine-remove.md')]
[PosixPath('index.md'), PosixPath('.'), PosixPath('en/index.md'), PosixPath('en/index.md')]
[PosixPath('cli/index.md'), PosixPath('index.md'), PosixPath('en/cli/index.md'), PosixPath('en/cli/index.md')]
[PosixPath('cli/machine-new.md'), PosixPath('machine-new.md'), PosixPath('en/cli/machine-new.md'), PosixPath('en/cli/machine-new.md')]
[PosixPath('cli/machine-remove.md'), PosixPath('machine-remove.md'), PosixPath('en/cli/machine-remove.md'), PosixPath('en/cli/machine-remove.md')]
[PosixPath('index.md'), PosixPath('.'), PosixPath('pt/index.md'), PosixPath('en/index.md')]
[PosixPath('cli/index.md'), PosixPath('index.md'), PosixPath('pt/cli/index.md'), PosixPath('en/cli/index.md')]
[PosixPath('cli/machine-new.md'), PosixPath('machine-new.md'), PosixPath('pt/cli/machine-new.md'), PosixPath('en/cli/machine-new.md')]
[PosixPath('cli/machine-remove.md'), PosixPath('machine-remove.md'), PosixPath('pt/cli/machine-remove.md'), PosixPath('en/cli/machine-remove.md')]
Page(title='Home', url='pt/')
Section(title='Documentation')
    Section(title='CLI')
        Page(title=[blank], url='pt/cli/')
        Section(title='Commands')
            Section(title='machine')
                Page(title='machine new', url='pt/cli/machine-new/')
                Page(title='machine remove', url='pt/cli/machine-remove/')
INFO     -  Translated navigation to pt
[PosixPath('en/cli/machine-new.md'), PosixPath('cli/machine-new.md'), PosixPath('en/en/cli/machine-new.md'), PosixPath('en/en/cli/machine-new.md')]
INFO     -  Building en documentation
[PosixPath('en/cli/machine-new.md'), PosixPath('cli/machine-new.md'), PosixPath('en/en/cli/machine-new.md'), PosixPath('en/en/cli/machine-new.md')]
INFO     -  Building pt documentation
[PosixPath('en/cli/machine-new.md'), PosixPath('cli/machine-new.md'), PosixPath('pt/en/cli/machine-new.md'), PosixPath('en/en/cli/machine-new.md')]
WARNING  -  Documentation file 'en/cli/machine-remove.md' contains a link to 'en/cli/machine-new.md' which is not found in the documentation files.
INFO     -  Documentation built in 0.27 seconds

The warning points to a link to a file not on the documentation files, but it is there.

Thank you for all the effort working on this issue so far.

hhslepicka commented 1 year ago

@ultrabug do you have an update? Is there anything I can do to help?

ultrabug commented 1 year ago

Sorry @hhslepicka ; hard to find time lately.

About navigation.indexes, please let's keep this to a separate issue once the main 404/links are fixed here.

I found out why those internal links are failing and pushed a fix on the branch. Local testing of your project works perfectly now I think.

What's your opinion?

hhslepicka commented 1 year ago

@ultrabug I apologize for the very late reply. I will get back to my tests this week and reply with proper testing on my side. Thank you for your time and for looking into this issue.

ultrabug commented 1 year ago

I updated the PR so that it's ready to be merged @hhslepicka

I'd like to get this in before moving back to the PR/Issue queue so I'll allow 24H delay before merging and moving on; I'm not trying to put pressure on you, just saying so that we can address any leftovers on newer issues afterwards

hhslepicka commented 1 year ago

@ultrabug I can get back to you on that today. Thank you!

ultrabug / mkdocs-static-i18n