Let gitbook process .md files outside of SUMMARY.md

[achton]

It seems to me that there is no way to create pages that are not part of the SUMMARY.md?

Ie. from README.md I would like to create a [link to a page](./core-update.md) where core-update.md is not part of the SUMMARY.md.

What happens is that the link itself is altered to link to the corresponding .html output file, but in reality the .md file itself is moved into the output dir, eg:

-rw-rw-r-- 1 aw aw    10 Mar 18 22:58 core-update.md
-rw-rw-r-- 1 aw aw 15016 Mar 18 22:58 faq.html
-rw-rw-r-- 1 aw aw 14862 Mar 18 22:58 git.html
drwxrwxr-x 2 aw aw  4096 Mar 18 22:58 ng
-rw-rw-r-- 1 aw aw 14861 Mar 18 22:58 README.html

How can I create pages that do not appear in the summary?

[aschempp]

I do have the same problem. I would probably be able to provide a pull request for that, but I have no idea what the best approach would be? I think simply processing all markdown files is not the ideal solution. Should we configure the additional files in the book.json? Or add something to the summary that is not added to the navigation?

[jonjack]

Would be a useful feature I think. Similar issue here was closed.

[ClintH]

👍

[solacerg]

👍

[mweststrate]

👍

[luisherranz]

ouch!

👍

[ekristen]

bump .. +1 to this

[jsntn]

+1

[bandantonio]

+1 This is a highly requested feature for me

[jmmiracle]

we need this feature too.change the validation rules of summary.md. allow empty dir name

[nilswald]

+1
a possible solution could be to at least follow (and process) all links in the book

[rafecolton]

A workaround is to add them to SUMMARY.md and hide them with CSS, but it's kind of ugly:

.summary .chapter[data-path="file.html"] {
  display: none;
}

[AaronO]

I see there's a lot of interest here in this issue, can you provide a few user-stories so we can better understand the use case and if it makes sense support it out of the box without any hacks.

[bandantonio]

@AaronO Below is our real world case that we cannot implement due to this limitation.
Currently we have API-related documentation and we created a step-by-step guide describing how to configure test environment, so people can play around with API requests. We want to just include this guide somewhere in the body as a hyperlink and refer to it from another gitbook page as a source of additional information. This guide is not intended to be listed in SUMMARY as a separate section according to the existing doc structure.

I think there are many other examples when some pages should not be included in SUMMARY, but they should be somewhere in text. By adding some secondary pages in SUMMARY with the only purpose to make them available throughout gitbook (as currently there is no other workaround) can make a real mess in structure and mislead readers.

[rafecolton]

I think there are many other examples when some pages should not be included in SUMMARY, but they should be somewhere in text. By adding some secondary pages in SUMMARY with the only purpose to make them available throughout gitbook (as currently there is no other workaround) can make a real mess in structure and mislead readers.

@AaronO our use case matches the above sentiment pretty exactly. Being able to exclude pages from the nav while still compiling them helps to balance the length of the side nav with the length of individual pages.

I recently wrote a page where one section under an H2 was about 3 times as long as the other sections on the page. I split it out into its own page so the canonical page flowed better, but that separate page is only relevant in the context of the canonical page from which it was split. So someone might be given direct access to the sub page or might click into it from the canonical, but they would never need to access it from elsewhere in the book. Given that, I didn't want to make the nav any longer than it has to be.

NOTE: There are also use cases for not compiling select pages. For example, if we want to include raw markdown into a different layout such as in https://github.com/rafecolton/presentation-tool. It would be helpful to also retain the ability to not compile certain pages. Probably better to assume all pages need to be compiled and provide an explicit way to leave a page as markdown.