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

Using # for section titles with --base-header-level=2 instead of using ## ? #63

Open
larmarange opened this issue Nov 14, 2018 · 2 comments
Open

Using # for section titles with --base-header-level=2 instead of using ## ? #63

larmarange opened this issue Nov 14, 2018 · 2 comments

Comments

@larmarange
Copy link

larmarange commented Nov 14, 2018 •
edited
Loading

As many other HTML templates, radix is using h1 for the title of the article and h2 for the different sections.

Following this, the corresponding expected markdown is something like:

---
title: "title of the article"
---

## Section 1

text

## Section 2

### Sub-section 2.1

text

This use of h2 for level-1 section headers is due to a historical limit of HTML (with not proper <title> or equivalent in the <body>).

However, for LaTeX or Word output, it is expected to use # for the level-1 section headers, which is semantically more correct.

One interest of markdown is the possibility to transform it into different outputs. However, currently, the markup of level-1 sections (## expected for HTML/radix vs # for LaTeX/Word output) is a problem.

Ideally, the markup in the markdown should not depend on the type of output.

A possibility could be for radix articles to expect the following markdown:

---
title: "title of the article"
---

# Section 1

text

# Section 2

## Sub-section 2.1

text

and to use the pandoc option --base-header-level=2 to properly transform # into <h2> keeping the same semantic of # between HTML, LaTeX and Word, while having the appropriate HTML markup.

As Radix is still in the development phase, would it be an appropriate time to discuss the relevance of such behaviour?
@jjallaire
Copy link
Member

Yes, this would indeed be great (as it would be both semantically better and would enable use of pandoc section numbers). That said, Radix is derived from the Distill framework (https://github.com/distillpub/template) which in turn currently requires H2 for in-document headings.

@larmarange
Copy link
Author

Using # for sections with --base-header-level=2 pandoc option will correctly turn section titles into <h2> HTML elements, as expected by the Distill framework. The advantage would be to be more correct semantically and to use the same markdown content for producing a Word or PDF document (Note: for these outputs, the pandoc option --base-header-level should be set to 1).

However, it will not resolve the issue of numbering sections discussed in https://github.com/rstudio/radix/issues/56). The problem is that Pandoc apply --number-sections after applying --base-header-level. I have raised that issue on Pandoc's GitHub (jgm/pandoc#5071).

@larmarange larmarange changed the title Using # for section titales with --base-header-level=2 instead of using ## ? Using # for section titles with --base-header-level=2 instead of using ## ? Dec 18, 2018
@Wandmalfarbe Wandmalfarbe mentioned this issue Sep 2, 2019
Closed
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
@jjallaire @larmarange