build is overeager to delete files in destination

[Xaeroxe]

In my repository I have folder called /book which contains the src files of our book. I, not entirely knowing what I was doing with mdbook ran mdbook build in the root of the repository. This builds a new book, and overwrote the src files in /book. Luckily this is a git repository so I didn't lose everything but I did lose about a half hour of writing. In order to prevent this in the future I'd recommend trying to detect if the files at the location mdbook is deleting from are actually html files from a previous build. If they are not, display an error: "directory_name_here is not empty and no html files were found, aborting, please remove files from this directory before continuing."

[azerupi]

I suppose we could perform a couple of basic checks before deleting everything. I think I already heard someone making the same mistake and if we can avoid blindly deleting peoples work, then we should do it.

[Xaeroxe]

Alternatively: requiring that a book.toml file be present would also avoid this in most circumstances.

[Michael-F-Bryan]

In order to prevent this in the future I'd recommend trying to detect if the files at the location mdbook is deleting from are actually html files from a previous build

I'm not sure whether there's an easy way to do this.

MDBook is actually designed so it won't delete the build directory to allow backends to implement caching. I'm assuming it's the HTML renderer which is deleting everything in its build directory, so I guess we could always tell it to abort if it finds anything which isn't HTML, CSS, or JS... Although this may not work because people can include arbitrary items (images, example code, etc) in their src/ directory and have it copied into the final build directory.

[SichangHe]

The question is why should HtmlHandlebars clean the output directory before it renders. For a clean mdbook build, this may be explained as ensuring that the build would be consistent. For mdbook serve, it could be that we want to ensure that we get rid of the deleted chapters.

However, the output directory may not only include artifacts from mdbook itself. For example, the mdbook-katex preprocessor could download a stylesheet and fonts into that directory, and in the current setup, the stylesheet and fonts would be downloaded every time mdbook build refreshes, which is very inefficient.

This issue has been open for 5 years, @ehuss. I want to do something about it.

I see several options:

1. Leave the option to the user and do not clean the output directory by default.
2. Clean the output directory if the command is mdbook build. If the command is mdbook serve, only clean it the first time.
3. Clean the output directory by default and provide a flag to not clean it.
4. Write a record file that specifies which files mdbook produced and check to delete a file only if it was created by mdbook.

Feel free to propose other options.

If we can agree on an option, I can make a PR for that.

[SichangHe]

For future reference, link to where HtmlHandlebars cleans its output directory, and it is called initially in build.

[Xaeroxe]

Perhaps a directory name with greater entropy would help i.e. mdbook-output

[SichangHe]

Perhaps a directory name with greater entropy would help i.e. mdbook-output

How would that help? Could you elaborate on that?

[Xaeroxe]

Sure. So the problem I ran into was that in my repository the source files are contained in a directory called “book”, which makes sense for us because we store other things in the repo too. However that’s the same directory name used for mdbook output. So, adding more entropy to the directory name decreases the chances that the user will also have a directory with that name.

[SichangHe]

Sure. So the problem I ran into was that in my repository the source files are contained in a directory called “book”, which makes sense for us because we store other things in the repo too. However that’s the same directory name used for mdbook output. So, adding more entropy to the directory name decreases the chances that the user will also have a directory with that name.

But, I suppose that you would have book/book as your mdbook build destination and there would not be a problem. I believe in your case you just need to set build-dir to mdbook-out, right?

[Xaeroxe]

Correct, those would have worked. What I was complaining about originally was a usability paper cut that I experienced as a result of not understanding how to operate the tool. Knowing how to operate the tool would have prevented this.