📖 Document include for splitting a document across multiple parts

[choldgraf]

Inspired by this discussion:

• https://github.com/orgs/executablebooks/discussions/1182#discussioncomment-9540505

This adds a short description of how you can split a document across many parts. I figured it's worth documenting since this is a very common workflow. @matthewfeickert curious if you would have found this here?

[matthewfeickert]

curious if you would have found this here?

Thanks @choldgraf! I think that adding this sort of stuff in explicitly is good, though I'm not sure if I would have found it or not as I was searching the docs on "multiple files"

and "separate files"

Had I read a bit better and clicked on the second result for "seperate files" I would have gotten to the directive reference docs, which does provide the information that I needed.

Though looking at the source file in your PR, I see that this is in a different section of the docs under Guide -> Documents -> Exporting documents, and looking around there more I see the docs that I actually wanted to find (but wouldn't have found in search) are Guide -> Authoring -> Embed & Include Content -> The {include} directive.

So that's a bit of a summary of my misadventure in finding the information, but moving this docs addition under Guide -> Authoring -> Embed & Include Content

(maybe around

https://github.com/executablebooks/mystmd/blob/683fd567830ec44651ac1daed8db2180850a95d6/docs/embed.md?plain=1#L147-L150

)

might be more useful.

[choldgraf]

Yeah that way I'm thinking about it is that we want that inlude/embed section to be the "source of truth", and then to have lots of breadcrumbs in other parts of the docs that lead you back to that section. AKA I'm trying to figure out where to sprinkle those breadcrumbs throughout. Maybe this needs to add the keywords like "multiple files", "separate files", etc in the {include} docs and that would be enough?

[matthewfeickert]

I'm trying to figure out where to sprinkle those breadcrumbs throughout.

Nice, I like the approach. 👍

Maybe this needs to add the keywords like "multiple files", "separate files", etc in the {include} docs and that would be enough?

Yeah, perhaps. I thought the same thing but didn't make it as a suggested change in this PR as while that would have been enough for me I'm not sure if everyone else is going to be looking for the same phrases. That being said, I don't think adding them in would detract/hurt.

[matthewfeickert]

Yeah, this example added to docs/embed.md is useful. Thank you!

[rowanc1]

Thanks both! This is great. 🚀