Skip to content
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.

Sign up for GitHub

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

Jump to bottom

lingering lack of full control over TOC / table of contents #5784

Closed
malcook opened this issue Oct 3, 2019 · 6 comments
Closed

lingering lack of full control over TOC / table of contents #5784

malcook opened this issue Oct 3, 2019 · 6 comments

Comments

@malcook
Copy link

malcook commented Oct 3, 2019 •
edited
Loading

I think the resolution to #2872 should be reconsidered.

I find its attempt to maintain backwards compatibility with interpretation of the toc metadata ultimately fails. I think the changes to the writers that assign the value of table-of-contents to toc should be reverted, while keeping all other changes.

Keeping it as-is, and setting toc to the value of table-of-contents causes a TOC section to be rendered by the template even if toc: false appears in YAML.

In short: let 'toc' be the boolean switch ONLY, and have 'table-of-contents' hold the, erhm, well, the pandoc rendered TOC.

The accordingly adjusted commit message would be, instead of:

For backwards compatibility, toc is still set to the
toc contents. But it is recommended that you update templates
to use table-of-contents for the toc contents and toc
for a boolean flag.

rather:

toc is no longer set to the
toc contents. You MUST update templates
to use table-of-contents for the toc contents and toc
for a boolean flag.

Then, what I think remains is:

  • everyone updates their templates as needed
  • pandoc is further changed to only compute a table-of-contents if toc is true, determined after consulting:
    • YAML header(s?) (for toc: true)
    • command line (for --toc or M toc=true)

After that, it would be grand to allow specifying in YAML header the (default) output format and (default) template to be used for that format... #5584 (analogous to RMarkdown's Output formats).
@jgm
Copy link
Owner

jgm commented Oct 3, 2019

What version of pandoc are you using?
With current HEAD and

pandoc -s
---
toc: false
...
^D

I get no table of contents.

@malcook
Copy link
Author

malcook commented Oct 3, 2019

Hi - I am using 2.7.3

I think I might have been up too late last night and made incorrect observation. Thanks for the correction.

However, still, should I expect to be required to call pandoc with --toc in order for table-of-contents to be set even if there is a toc: true directive in the YAML? I find (somewhat counter-intuitively, but perhaps understandably), that toc: true will emit an empty <nav id=TOC...> section when I call pandoc without --toc.

Example:

pandoc -s
---
toc: true
title: test
...
# this is h1
hello
^d
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="" xml:lang="">
<head>
  <meta charset="utf-8" />
  <meta name="generator" content="pandoc" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
  <title>test</title>
  <style>
      code{white-space: pre-wrap;}
      span.smallcaps{font-variant: small-caps;}
      span.underline{text-decoration: underline;}
      div.column{display: inline-block; vertical-align: top; width: 50%;}
  </style>
  <!--[if lt IE 9]>
    <script src="//cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv-printshiv.min.js"></script>
  <![endif]-->
</head>
<body>
<header id="title-block-header">
<h1 class="title">test</h1>
</header>
<nav id="TOC" role="doc-toc">

</nav>
<h1 id="this-is-h1">this is h1</h1>
<p>hello</p>
</body>
</html>

@jgm
Copy link
Owner

jgm commented Oct 3, 2019

Correct. You must use --toc. In a few formats, it will work just to set toc in metadata, but that's only because it's sufficient in these formats to set a specific command which is found in the template, under $if(toc)$. This works but it's not a "supported" feature.

@malcook
Copy link
Author

malcook commented Oct 3, 2019

Understood. Makes better sense now. So, for example, a template of course could introduce anything, possibly including (in the case of -t html) introducing javascript/css which onLoad parses the html DOM and builds a toc (floating, colored, whatever) "on the fly". Right?

On related topic, is there any way of pandoc getting the URL or path to the template from the YAML front matter? Would this be consistent with your vision?

@jgm
Copy link
Owner

jgm commented Oct 3, 2019

So, for example, a template of course could introduce anything, possibly including (in the case of -t html) introducing javascript/css which onLoad parses the html DOM and builds a toc (floating, colored, whatever) "on the fly". Right?

Yes.

is there any way of pandoc getting the URL or path to the template from the YAML front matter? Would this be consistent with your vision?

No and no. A given document could be rendered to many different formats, each with a different template.

@malcook
Copy link
Author

malcook commented Oct 3, 2019

Thanks for your thorough consideration and guidance.

@malcook malcook closed this as completed Oct 3, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
2 participants
@jgm @malcook