Open Xenonym opened 5 years ago
Oh? I never used it because I didn't know about it. I don't mind keeping it as it can be useful for printer-friendly versions of a page. Also, the page nav disappears at small screen sizes which means a ToC is not entirely useless. Shall we document it?
@damithc some caveats found while testing this feature:
markdown-it
plugin, HTML headings will not be included in the TOC as they will not be parsed as Markdown.markdown-it
initalisation, meaning there is no way for the user to specify their own heading level in Markdown. If we want to allow a user the same degree of control over the TOC headings as we do with page nav headings, we may have to build this feature ourselves.
- Since this is a
markdown-it
plugin, HTML headings will not be included in the TOC as they will not be parsed as Markdown.
I see. Should be fine I guess.
- The default settings only include headings level 1 and 2, and are only configurable at
markdown-it
initalisation, meaning there is no way for the user to specify their own heading level in Markdown. If we want to allow a user the same degree of control over the TOC headings as we do with page nav headings, we may have to build this feature ourselves.
I guess this will have to do, until we create our own (or fork the current plugin)
But make sure the plugin is compatible with our include
feature i.e., it captures headings in the included files too.
A follow up:
It looks like the [[toc]]
in its current form does not work correctly with include
. i.e., If I include a file that contains a [[toc]]
, the output shown in the host page matches the headings of the host page rather than the original page.
This is because Markdown is rendered later, for efficiency.
I think Markdown is only rendered once per page. Rendering rendered Markdown may have undefined behavior.
I suppose it works with dynamic include?
I suppose it works with dynamic include?
It should work for boilerplate includes because the behavior matches boilerplates (i.e., copy content and then render).
Boilerplate includes can be static or dynamic right?
Boilerplate includes can be static or dynamic right?
No such differentiation as far as the current documentation goes.
[[toc]]
works in the second way.
I have a vague memory of having dynamic includes but it seems to have fallen through the cracks along the way. I remember trying to use that feature but couldn't get it to work.
Boilerplate includes can be static or dynamic right?
No such differentiation as far as the current documentation goes.
Sorry, I mixed it up with static (preload) and dynamic panels.
- Default: render content in original location and then copy over
- Boilerplate: copy over content and then render based on the new location
Should be:
copy over content and then render based on the new location
vs render content based on the included location and then copy over to includer
From the user's PoV, is there a difference? The former is easier for the end-user to understand.
The former is missing "copy over" at the end. Whether or not the user's PoV has an additional "copy over" at the start is of less significance.
I didn't think of it when I was revising the boilerplate documentation but later I realized that a simple way to explain the boilerplate behavior is: it is equivalent to copy-pasting the content as is into the included location and then interpreting it. Whereas, normally the content is interpreted in-place and then the result is copy-pasted into the included location. Is that explanation correct, at least from the users PoV?
Nope. If I remember correctly:
it is equivalent to copy-pasting the content as is
from the original location
into the included location and then interpreting itin the included location and then the result is copy-pasted into the includer location
. Whereas, normally the content is interpreted in-placein the included location
and then the result is copy-pasted into the ~included~includer
location.
The "copy-pasting" at the start makes it a boilerplate. The "copy-pasted" at the end makes it an include.
Extracting the common part:
it is equivalent to copy-pasting the content as is
from the original location
into the included location and then interpreting it{{ 1 }}
. Whereas, normally the content is interpreted in-place{{ 1 }}
where {{1}}
is:
in the included location
and then the result is copy-pasted into the ~included~includer
location.
Got it. I forgot there are three (not two) locations involved in a boilerplate inclusion.
If includes don't work, is this still worth documenting? Combined with the earlier caveats of fixed heading levels and Markdown-only, documenting a feature with so many exceptions may end up confusing a user and giving a bad impression of the overall product, which I think outweigh the benefit of having a useful feature.
If includes don't work, is this still worth documenting? Combined with the earlier caveats of fixed heading levels and Markdown-only, documenting a feature with so many exceptions may end up confusing a user and giving a bad impression of the overall product, which I think outweigh the benefit of having a useful feature.
Yes, it has far too many flaws ATM. We can keep it undocumented until we make it play nice with other MarkBind features. In particular, I would like it to be able to generate a ToC of an another page so that I can use it to create site/page maps.
Example:
siteMap.md
:
<include src="chapter1.md#toc" />
<include src="chapter2.md#toc" />
chapter1.md
:
<variable name="toc">
[[toc]]
</span>
Raising the priority to be high as a table of content could be important for CS2103T tP documentation migration
To deal with the include problem, I am thinking of removing the markdown-it-table-of-contents plugin and abstracting the logic of the existing pageNav renderer so that it can be used to generate both a page nav, as well as a TOC.
Syntex wise we can still use "[[toc]]" to indicate the place to put the TOC. The initial implementation will have limited configurations, i.e it follows the levels set for pageNav in terms in headingIndexingLevel.
The main purpose is to create printer-friendly versions of a page.
Any feedback/comments are welcomed.
a huge plus if we can reuse and generalise the same logic as the <pagenav>
component
Professor Damith remarked in the discussion that he is open to retaining the feature as it could enhance the production of printer-friendly page versions. Given that the capability to print the page-navigation has been successfully implemented (as evidenced by Pull Request #2069), the continued use of markdown-it-table-of-contents seems superfluous.
Tell us about your environment
We include the
markdown-it
pluginmarkdown-it-table-of-contents
, which generates a table of contents based on Markdown headings where a[[toc]]
tag is placed. For example, here's the Formatting Contents user guide page with a[[toc]]
tag:However, we never seem to have documented this feature. Additionally, it seems that the role of a table of contents is already better served by page navigation menus.
markdown-it-table-of-contents
for any other feature? If not, we should probably remove it.FYI:
markdown-it-table-of-contents
was added in 6eca765 on March 7, 2017 😮