-
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
mdBook for multi-repo github org #1347
Comments
/cc @Michael-F-Bryan, |
Is there something stopping you from updating the |
No, there isn't. I actually didn't know that we could do it from within the Netlify.
|
Admittedly I'm not familiar with Netlify, but I'd hope there's a way to execute git commands. In any case, is there a feature request here for mdBook? Wondering what action there is for mdBook maintainers to take from your workflow you're attempting |
I’m not sure if I can call it a feature request. My intention was to discuss with the mdBook community to see if I can get some help on my specific issue. Because, we are interested in using mdBook and I thought maybe you have experienced a similar challenge. |
What about giving That way you could have a top level # Summary
- [overview](index.md)
- {{#import "Repository A" "./a/book/src/SUMMARY.md"}}
- {{#import "Repository B" "./b/book/src/SUMMARY.md"}}
- [Conclusion](conclusion.md) And - [First](first.md)
- [Second](second.md) And - [First](first.md)
- [Second](second.md)
- [Third](third.md) (the duplicate names are intentional) Then the parser would expand all annotations of the form # Summary
- [overview](index.md)
- Repoistory A
- [First](./a/book/src/first.md)
- [Second](./a/book/src/second.md)
- Repository B
- [First](./b/book/src/first.md)
- [Second](./b/book/src/second.md)
- [Third](./b/book/src/third.md)
- [Conclusion](conclusion.md) Then whenever you make docs changes in a submodule the top level repository does a I'm not sure how this import mechanism would interact with things set in the submodule's |
@Michael-F-Bryan Thanks for the comment. I really like the idea of And |
I have an issue like this, i use mdbook as an Onenote like for now. I have one book and i write multiple book in it. It's ok for 2-3 book but for more is not easily readable. What about and architecture like this:
but with this:
I don't think its gonna solve the whole problem about Netlify but, for my use case it would be a must. |
In case anyone finds this helpful: We made an extremely hacky approach work for this sort of thing. While we don't have multiple repos, we want to compile code as part of the book building process. So we abuse the preprocessor hooks to do that, both for a compiled text editor, and an in-tree preprocessor: https://github.com/prql/prql/blob/ae053d9c5547f91317ea11cf5f957270ca366804/reference/book.toml |
This feature could be something nice to have. Plus on this, it might be even helpful if we could allow mdbook to print all the markdown files under a specific folder recursively and the pages just organized by path and file names, or the first line of If this is can be done, then in repo A we can have
and in repo B we can have
Then in the summary of another "main" repo, where we have folder
This could be very helpful for small orgnizations to use mdbook to create a centralized doc site for multiple of their github repositories. And mdbook config is only in the main/master repo, while all the md fils are just laying around in each repo. Each repo owner can use file structure and first line of the md file to define the chapter/page headlines. |
I also use mdbook with multiple repos as it's most effective to keep docs close to the source. The SUMMARY.md at least makes this possible. One minor problem is the edit link does not work in submodules. Looking forward to additional improvements! |
Hi,
Thanks a lot first of all for the amazing work with mdBook.
I wanted to discuss/check out with mdBook contributors if there is a way to solve the problem we are facing currently.
Basically, we have multiple repositories under a single github organization. Each repository has its own documentation. What we want is that - a single mdBook based book that would fetch documentations from all our repositories and show it to the user as a single book.
I will try to use example repositories to be more clear. Let’s say we have
example
github organization, withx, y, z
repositories under it.Our wish is - whenever there is a pull request in any of the
x, y, z
repositories that introduces documentation changes, we want to have a preview with netlify on the corresponding repository. This brings the following problems:x, y, z
repositoryOne way that we came up was that - we have a separate repo w for storing documentation of all the other repositories. But we are not moving the docs from
x, y, x
to w but instead we clonex, y,
andz
as submodules into thew
repo. The reason for not moving them to thew
repo is because we would like to keep the documentation as close as possible to the repository that it corresponds to. This will work, we could start the mdbook fromw
repo + including content ofx, y, z
that we submoduled. And there will be automated CI that will be updatingw
repo for example every night with the changes introduced inx, y, z
. But this also brings some problems when renewing a PRx
repo and we want to show the changes on netlify to the PR author. So, netlify will try to fetch the content from the w repository(which doesn’t include current commit inx
repo). But since w repo has no idea about the PR onx
repo, we can’t really show the preview with the actual changes being introduced with the current commit.In short it is problematic to have a single book that will be sourcing contents from multiple repositories.
I would really love to hear your inputs and open for a discussion.
Thanks in advance.
The text was updated successfully, but these errors were encountered: