Unlisted headers (\section*{}) equivalent

[jurf]

Hi,

is there a way to add headers that should be ignored by the ToC in markdown? All I found was #401 but not this. Unfortunately my current project needs them extensively, so I currently have to resort to raw \section*{} tags.

[Witiko]

Hi. After you have enabled the option headerAttributes, you should be able to write either {-} or {.unnumbered} after headings:

\documentclass{article}
\usepackage[headerAttributes]{markdown}
\begin{document}
\begin{markdown}
# Here is a numbered section
## Here is an unnumbered subsection {-}
### This subsection will be unnumbered as well
## Here is a numbered subsection
\end{markdown}
\end{document}

[Witiko]

Sadly, Overleaf is ca 6 months out-of-date and still uses version 3.4.2 of the Markdown package from March while the latest released version is 3.7.1 from September.

If all you want are better defaults that support unnumbered sections out-of-box, you can include an up-to-date file markdownthemewitiko_markdown_defaults.sty in your Overleaf project, see also my example Overleaf project.

However, new TeX interfaces were added to the Markdown package since version 3.4.2, most notably the support for incremental renderer (prototype) definitions, added in version 3.5.0 from April.

The updated file markdownthemewitiko_markdown_defaults.sty uses the new interfaces for the new definitions of unnumbered sections. Therefore, they happen to work with version 3.4.2 only by a lucky accident. Furthermore, there have been many other new developments and bugfixes by me and @lostenderman since version 3.4.2, see also the changelog.

Therefore, if you are serious about using the Markdown package on Overleaf, you may want to consider installing the current version of the Markdown package into your Overleaf project, see also my example Overleaf project. Alternatively, you may want to use an environment with an up-to-date TeX installation other than Overleaf, such as your laptop and the texlive/texlive Docker image.

[jurf]

Ah, I understand, thanks. Sorry, even after years with LaTeX, it can be overwhelming.

However, even after adding the latest version and successfully removing the numbers, the sections still show up in the ToC.

I updated the initial example: https://www.overleaf.com/read/kpbdzzttpjqh#8f7af1

[jurf]

Btw, I solved this for now by limiting the depth of the ToC which so far works in my current use-case.

[Witiko]

However, even after adding the latest version and successfully removing the numbers, the sections still show up in the ToC.

This is as expected. The LaTeX command \section* is a low-level command that only formats a text to look like a heading without creating an entry in the table of contents, updating the running heads, creating a target for a hyperlink, or doing any of the other tasks that are necessary for a proper heading. By contrast, the default renderer for Markdown creates a regular heading, just without the numbering. In my experience, this is what is usually wanted in a document. However, I recognize that you asked specifically for a version that excludes the section from the table of contents.

If you'd like to translate ## Section name to \section*{Section Name} instead, you can type the following in the preamble:

\markdownSetup {
  renderers = {
    headingTwo = {\section*{#1}},
  },
}

If you'd like to do this conditionally just for ## Section name {-} and not ## Section name, then you need a more complex setup that would react to attribute values. Look for \l__markdown_header_unnumbered_bool in the file markdownthemewitiko_markdown_defaults.sty to see how it's done in the default definitions.

Btw, I solved this for now by limiting the depth of the ToC which so far works in my current use-case.

I am glad that you found a solution that works for you.

[jurf]

limiting the depth of the ToC which so far works in my current use-case

Turns out that wasn't enough so I tried creating the new renderer. I somehow managed to pound your instructions with a hammer until something useable came out of it. :) If anyone needs this in the future, this renderer seems to work. There is no guarantee, I really just added hashes at what looked like the most probable space until it started working.

\ExplSyntaxOn
\markdownSetup
  {
    rendererPrototypes = {
      headerAttributeContextBegin += {
        \markdownSetup
          {
            rendererPrototypes = {
              attributeClassName = {
                \bool_if:nT
                  {
                    \str_if_eq_p:nn
                      { ##1 }
                      { unnumbered } &&
                    ! \l__markdown_header_unnumbered_bool
                  }
                  {
                    \group_begin:
                    \bool_set_true:N
                      \l__markdown_header_unnumbered_bool
                    \markdownSetup
                      {
                        renderers = {
                          headingTwo = {\section*{####1}},
                          headingThree = {\subsection*{####1}},
                          headingFour = {\subsubsection*{####1}},
                        },
                        rendererPrototypes = {
                          sectionBegin = {
                            \group_begin:
                          },
                          sectionEnd = {
                            \group_end:
                          },
                        },
                      }
                  }
              },
            },
          }
      },
    },
  }
\ExplSyntaxOff