Linking files above the docs_dir

[ba66e77]

Details

• Read the Docs project URL:
• Build URL (if applicable):
• Read the Docs username (if applicable):

Prior to the update of the mkdocs package referenced in #4231, we were able to link files above our docs_dir in the pages section of our mkdir.yml. Given a directory structure of ..

mkdocs.yml
index.md
README.md
INSTALL.md
readme/
    windows-install.md
    local-development.md

...we were able to link successfully with a pages section in our mkdocs.yml like this:

pages:
  - Home: 'index.md'
  - Overview: 'README.md'
  - Getting started:
    - Installation:
       - System requirements:  'INSTALL.md'
       - Running BLT in Ubuntu on Bash on Windows: 'readme/windows-install.md'
       - Alternative LAMP stacks: 'readme/local-development.md'

Since the mkdocs update, builds fail complaining that the files above the docs_dir cannot be found. We don't want to move the README.md and INSTALL.md out of the repo root. Is there some other way to successfully link them from this docs structure?

error message

INFO    -  Cleaning site directory 
INFO    -  Building documentation to directory: /home/docs/checkouts/readthedocs.org/user_builds/blt/checkouts/hopingidontbreakdocsanyfurther/_build/html 
ERROR   -  File not found: /home/docs/checkouts/readthedocs.org/user_builds/blt/checkouts/hopingidontbreakdocsanyfurther/readme/index.md 
ERROR   -  Error building page index.md 
Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/blt/envs/hopingidontbreakdocsanyfurther/bin/mkdocs", line 11, in <module>
    sys.exit(cli())
  File "/home/docs/checkouts/readthedocs.org/user_builds/blt/envs/hopingidontbreakdocsanyfurther/local/lib/python2.7/site-packages/click/core.py", line 722, in __call__
    return self.main(*args, **kwargs)
  File "/home/docs/checkouts/readthedocs.org/user_builds/blt/envs/hopingidontbreakdocsanyfurther/local/lib/python2.7/site-packages/click/core.py", line 697, in main
    rv = self.invoke(ctx)
  File "/home/docs/checkouts/readthedocs.org/user_builds/blt/envs/hopingidontbreakdocsanyfurther/local/lib/python2.7/site-packages/click/core.py", line 1066, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/home/docs/checkouts/readthedocs.org/user_builds/blt/envs/hopingidontbreakdocsanyfurther/local/lib/python2.7/site-packages/click/core.py", line 895, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/home/docs/checkouts/readthedocs.org/user_builds/blt/envs/hopingidontbreakdocsanyfurther/local/lib/python2.7/site-packages/click/core.py", line 535, in invoke
    return callback(*args, **kwargs)
  File "/home/docs/checkouts/readthedocs.org/user_builds/blt/envs/hopingidontbreakdocsanyfurther/local/lib/python2.7/site-packages/mkdocs/__main__.py", line 156, in build_command
    ), dirty=not clean)
  File "/home/docs/checkouts/readthedocs.org/user_builds/blt/envs/hopingidontbreakdocsanyfurther/local/lib/python2.7/site-packages/mkdocs/commands/build.py", line 282, in build
    build_pages(config, dirty=dirty)
  File "/home/docs/checkouts/readthedocs.org/user_builds/blt/envs/hopingidontbreakdocsanyfurther/local/lib/python2.7/site-packages/mkdocs/commands/build.py", line 242, in build_pages
    _build_page(page, config, site_navigation, env)
  File "/home/docs/checkouts/readthedocs.org/user_builds/blt/envs/hopingidontbreakdocsanyfurther/local/lib/python2.7/site-packages/mkdocs/commands/build.py", line 130, in _build_page
    page.read_source(config=config)
  File "/home/docs/checkouts/readthedocs.org/user_builds/blt/envs/hopingidontbreakdocsanyfurther/local/lib/python2.7/site-packages/mkdocs/nav.py", line 251, in read_source
    with io.open(self.abs_input_path, 'r', encoding='utf-8-sig') as f:
IOError: [Errno 2] No such file or directory: '/home/docs/checkouts/readthedocs.org/user_builds/blt/checkouts/hopingidontbreakdocsanyfurther/readme/index.md'

[stsewd]

As the examples in https://www.mkdocs.org/user-guide/writing-your-docs/#file-layout I don't think so, maybe you can try using symbolic links?

[ba66e77]

Drat. Symlinking technically works, but it breaks the relative links within those docs in one direction or the other (i.e., the links are either correct in the docs_dir and broken if someone views the file in github or vice versa).

Looks like it's time to do some docs restructuring.

[stsewd]

Looks like you were able to solve the linked issue, can we close this?

[ba66e77]

Yep, we're good. Thanks for the input.