-
Notifications
You must be signed in to change notification settings - Fork 1.6k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Use an optional .mdbookignore file to specify files to not copy to the output directory #1187
Comments
I might prefer just making it a field in the config, like But a question is, why add files to the src directory, but don't want them as part of the book? Why not just put those files somewhere else? |
On the why: It's due to the structure of my book. My book has a lot of it's content in a docs subfolder, BUT, it also includes README.md and other markdown files from multiple other sub-folders (it's a workspace rust project with multiple crates) so the docs files are mixed in with the code tree structure. With the fix to avoid the recursive directory copy you merged recently I can now have my book.toml and SUMMARY.md in the root folder of the project, and SUMMARY.md includes entries for those multiple crates in sub-directories. This leads to all sorts of files being copied into the output folder, such as: I currently have a make target that deletes all the extra before doing the gh-pages deploy, cutting down the size of the upload considerably. |
In my case, I'm using some helper files in
That would be enough. |
To give my own specific example of the files that are copied and undesirable, here is the additiional make target I have had to add to cleanup the output directory before all of these are uploaded to gh_pages:
That would be pretty noisy/complex as a set of config file patterns, which made me think of a .ignore file |
I'm back looking at this. |
I prefer to have documentation located close to the source files in the repo when possible. This helps ensure that the documentation is maintained.
Lately, I've also been using mdbook to pull documentation from multiple repos to build one book -- add all the repos that have docs to a superproject using git submodules, and then the SUMMARY.md simply points to the docs where-ever they might be. Overall, it works pretty well, but I have to clean out the build dir before deploying. Why does mdbook deploy all files? Would it be possible to just start with *.md files and then only include additional files that are linked from *.md files? |
Just to mention another use case: an mdbook used to publish student assignments. The solutions to published exercises should be kept in the same place as the assignments, but not published (at least not immediately) together with the exercises. I'd like to have a way to exclude them, and ideally one that is configurable, so that different publication workflows can include/exclude the solutions selectively. Thanks a lot for mdbook, it's awesome! |
Current Behaviour
Currently almost all files in the source directory are copied to the output directory, often copying unneeded or undesired files, which maybe uploaded to gh-pages or otherwise "published"
Proposed Change
Allow an optional “.mdbookignore” file (like .gitignore) to allow specifying patterns of files to ignore and hence NOT get copied during the build.
Implementation
If you provide comments, and the general idea seems acceptable, I would prepare a PR for this.
I would use the existing "ignore" crate from the ripgrep project, and using the provided method to override the name of the ignore file from ".gitignore" to ".mdbookignore"
The text was updated successfully, but these errors were encountered: