Adjust section level in included markdown files
olowo726 opened this issue · comments
Consider the following markdown
# Software components
## Platform
!include J1939Tp/J1939Tp.md
J1939Tp.md:
# J1939Tp
Implements the Transport Protocol (TP)
.
.
.
Then I would like the heading J193Tp to be on level 3 in the merge output. "Software components" is level 1, "Platform" is level 2. The filter should know the heading level at the point of include and adjust heading levels in included file accordingly. This makes it possible to reuse included .md files in several documents.
I believe you could use the incrementSection option to specify how many levels you want to increment. The reason for not detecting it automatically is that it will make it impossible to add some level 1 sections at the end (like the appendix)
incrementSection helps some but doesn't solve all cases. Consider for example nested includes. When writing a document which might be included the author doesn't know the current level and hence doesn't know desired increment.
How about incrementSection="auto"?
For incrementSeciont, the author of the included document doesn't need to know how many levels to increment. It's the responsibility of the author who wants to include other documents. Maybe I misunderstood your question. If so, could you provide an example to explain why the author doesn't know the current level?
Is it necessary for doc2 to know the the absolute level in doc1? incrementSection works by incrementing all the section levels. So as long as doc2 knows the how to set doc3's level relatively, it should work because doc1 can increment the levels of both doc2 and doc3 altogether
Yes I think so. It's based on the nature of recursive include. You can always try it easily to verify it when you doubt it.
I've tested now and it works as you say. So current functionality works but I still think incrementSection="auto" would be a nice feature (saving me some thinking and make it easier to rearrange).
Yes I think that may help. However, it's hard to define the auto behaviour as there's no end boundary for sections.
For example, if we have the following markdown:
# Sec 1
Section 1
# Sec 2
Section 2
!include file.mdWhat would you expect the incrementSection to be? It's reasonable to use either 0 or 1 here.
I see. It makes sense now. auto is a kinda confusing name as I originally thought you were suggesting a more intelligent approach. I would vote for current as it always needs to match with the current level.