Build artifacts can escape the output directory (book)

[japaric]

STR

$ mkdir foo && cd $_

$ touch README.md

$ edit src/SUMMARY.md && cat $_
- [foo](../README.md)

$ tree
.
├── README.md
└── src
    └── SUMMARY.md

$ mdbook build

$ tree
.
├── book
│   ├── book.css
│   ├── book.js
│   ├── favicon.png
│   ├── _FontAwesome
│   │   ├── css
│   │   │   └── font-awesome.css
│   │   └── fonts
│   │       ├── FontAwesome.ttf
│   │       ├── fontawesome-webfont.eot
│   │       ├── fontawesome-webfont.svg
│   │       ├── fontawesome-webfont.ttf
│   │       ├── fontawesome-webfont.woff
│   │       └── fontawesome-webfont.woff2
│   ├── highlight.css
│   ├── highlight.js
│   ├── index.html
│   ├── jquery.js
│   ├── print.html
│   └── tomorrow-night.css
├── README.html <-- !
├── README.md
└── src
    └── SUMMARY.md

There's an extra README.html in the root of the directory. I think the cause is that one of the input files is outside the src directory.

My expectation is that build artifacts should be contained in the book directory.

Meta

$ mdbook --verion
mdbook v0.0.15

$ git rev-parse HEAD
b91f8173503e017fc41ef3254e4726872d

[japaric]

Trying to hack around this using symlink shenanigans results in an error "File name too long (os error 36)":

$ mkdir foo && cd $_

$ ln -s . src

$ edit src/SUMMARY.md && cat $_
- [foo](./README.md)

$ touch README.md

$ tree
.
├── README.md
├── src -> .
└── SUMMARY.md

$ mdbook build
An error occured:
File name too long (os error 36)

[azerupi]

Thanks for the report!
So the problem originates form the fact that mdBook tries to keep the same structure in the output as the the one from the source files. But as you experienced, I didn't consider the case where files could be outside of the source directory.

The easiest solution would probably be to put any file coming from outside of src at the root level of the output.

[gilescope]

Example use case:

Using mdbook on a standard github project with a README.md in the root of the repository. Currently it's really hard to reference this file as it's not in src.

(Would be good if it would just dump anything below the output dir in the root of the output dir.)

[tv42]

I made my first chapter include the main README:

$ cat doc/intro.md
{{#include ../README.md}}

This breaks any relative links in README.md (unless they're to *.md and a similar trick is done for them), mostly LICENSE-APACHE and such that are very common.

It also breaks https://github.com/Michael-F-Bryan/mdbook-linkcheck (the README links to LICENSE-APACHE etc, which seem to be interpreted relative to that doc/intro.md, and if you try to symlink them there, then you get an error "Linking outside of the "root" directory is forbidden". The workaround for those is yet more stub files with {{#include}}. But then those aren't actually included in the book, because they're not in SUMMARY.md, and it's just ugly all around.)

Trying include just portions of README either succumbs to having to use brittle line numbers, or needing to litter README.md with anchors.

[SeWieland]

Example use case:

Using mdbook on a standard github project with a README.md in the root of the repository. Currently it's really hard to reference this file as it's not in src.

(Would be good if it would just dump anything below the output dir in the root of the output dir.)

This describes exactly my usecase. I'm trying to create a book out of existing README.md files + relative .md files to the Readme.

My approach is now to simply copy everything into a src folder during build. Not ideal, but the relative links should work.