Hi,
thanks for sharing your project!

This is just a thought, but it could be helpful to create a new organisation with two sub-project for example and integrate the publish of the doc with travis as sample/tutorial.
The third project (this one) will contain the merged documentations published on github.io with your tool from the other two.

Not sure if I can help somehow, but it was just an idea ;-)

It fails on "nav" section and does not apply "custom_dir" theme properly.

Hey there!

Firstly, thank you so much for this amazing tool!

In our company, we use it in combo with MkDocs Material. Not sure about original MkDocs, but in this version, there is an option to set index pages for sections. To get a better understanding, please take a look at feature description.

It's very simple, and what it means, is that basically you may now have a nav entry in mkdocs.yml that looks like this:

nav:
  - Home: index.md
  - Section:
    - section/index.md                             #   <--- this right here is new!
    - Page 1: section/page-1.md
    ...
    - Page n: section/page-n.md

Those kind of entries are currently not supported and result in "Error merging the "nav" entry in the site: xxxx".

I've taken a quick look at the code - to me seems like a new elif in recursive function update_navs should be added where nav can be instance of str, or sth like that.

I hope you'll have a bit of time to consider this.

Thanks!

Hey Oscar,

I just found your tool, as it is currently the only one I found so far for combining many docs into a single source. Still, you built a pretty awesome base that could be extended further. ;)

I found, that providing the "nav" entry in mkdocs.yaml is pretty useless as mkdocs will discover all the files by itself.
I am a little new to this topic. but am I wrong?

Hi @ovasquez , thank you for this useful tool!

I encounter an issue when in my mkdocs.yml of a sub-site I'm using special characters, such as !:

markdown_extensions:
  - pymdownx.emoji:
      emoji_index: !!python/name:materialx.emoji.twemoji
      emoji_generator: !!python/name:materialx.emoji.to_svg

for example when you setup this extension: https://github.com/facelessuser/mkdocs-material-extensions#inline-svg-icons

turns into:

❯ mkdocs-merge run master_site sub_site

Attempting to merge site: sub_site
Error loading the yaml file "sub_site/mkdocs.yml". This site will be skipped.

Sounds like the Ruamel Yaml parser is not working with such !! tag

First let me say thanks for this package. It's really good considering what I've seen out there and I've integrated it into my own package which I plan to open source in the near future. It's a mkdocs-merge-server which uses mkdocs-merge to merge multiple mkdocs documentation source packages and also serve the final merged website.

The problem that I hit with your package was that subsequent merges failed with a similar failure I saw here https://stackoverflow.com/questions/9160227/dir-util-copy-tree-fails-after-shutil-rmtree/28055993#28055993 where I also found the workaround.

So basically what I did was to do this this:

        distutils.dir_util._path_created = {}
        new_pages = mkdocsmerge.__main__.merge_sites(sites, self._main_site_folder, True)

Also, I have to admit that there was a bit of a friction when I use your package as a module due to the cli extensions and not a more detailed organization.

Say you have a mkdocs site with a setup.md that links to other windows.md, macosx.md and linux.md files like this:

setup.md

Here you can find the setup instructions for:
- [Windows](windows.md)
- [MacOSx](macosx.md)
- [Linux](linux.md)

When you merge that to any other master site, the references will point to a non-existing location.

The workaround is to have the links that point to the html's instead:

Here you can find the setup instructions for:
- [Windows](windows/index.html)
- [MacOSx](macosx/index.html)
- [Linux](linux/index.html)

... but that will break the static markdown files making them aware that they will be compiled to html at one point.

Would be nice if mkdocs-merge would do this automatically (and be aware of some other relative links to other directory structure).

Also, the problematic is extended for paragraph bookmarks (index.html#topic1).

How can we solve that in a more consistent way to make all files agnostic of where they are being used? I think this is an open question for later.

Hi @ovasquez,

Thank you for this nice tool!

We are using mkdocs-merge to add a separate site repository into a central (MASTER_SITE) site as a sub-page.

It appears that the treatment of the edit_uri for the sub-page does not link back (via the edit icon) to the original repository, but links back to the central one and returns an error.

Is there a way this can be treated properly?

Best regards,
Mateusz

Hi @ovasquez,

Suddenly mkdocs-merge stopped working for us:

Cloning into 'ps-instructions'...
$ mkdocs-merge run . ps-instructions
Attempting to merge site: ps-instructions
Traceback (most recent call last):
  File "/usr/local/bin/mkdocs-merge", line 8, in <module>
    sys.exit(cli())
  File "/usr/local/lib/python3.9/site-packages/click/core.py", line 1157, in __call__
    return self.main(*args, **kwargs)
  File "/usr/local/lib/python3.9/site-packages/click/core.py", line 1078, in main
    rv = self.invoke(ctx)
  File "/usr/local/lib/python3.9/site-packages/click/core.py", line 1688, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/usr/local/lib/python3.9/site-packages/click/core.py", line 1434, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/usr/local/lib/python3.9/site-packages/click/core.py", line 783, in invoke
    return __callback(*args, **kwargs)
  File "/usr/local/lib/python3.9/site-packages/mkdocsmerge/__main__.py", line 44, in run
    merge.run_merge(master_site, sites, unify_sites, print_func=click.echo)
  File "/usr/local/lib/python3.9/site-packages/mkdocsmerge/merge.py", line 35, in run_merge
    new_navs = merge_sites(sites, master_docs_root, unify_sites, print_func)
  File "/usr/local/lib/python3.9/site-packages/mkdocsmerge/merge.py", line 105, in merge_sites
    dir_util.copy_tree(old_site_docs, new_site_docs, update=1)
  File "/usr/local/lib/python3.9/site-packages/setuptools/_distutils/dir_util.py", line 146, in copy_tree
    mkpath(dst, verbose=verbose)
  File "/usr/local/lib/python3.9/site-packages/setuptools/_distutils/dir_util.py", line 82, in mkpath
    _path_created.add(abs_head)
AttributeError: 'dict' object has no attribute 'add'

https://gitlab.cern.ch/cms-tsg/fog/documentation/-/jobs/40713402

Could you please help us understand the underlying issue?

Thanks a lot.

Cheers,
Mateusz