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.

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

Support setext headings in Markdown #6013

Open
ExE-Boss opened this issue Mar 29, 2019 · 8 comments
Open

Support setext headings in Markdown #6013

ExE-Boss opened this issue Mar 29, 2019 · 8 comments
Labels
help wanted We're a small group who can't get to every issue promptly. We’d appreciate help fixing this issue! lang:markdown Issues affecting Markdown type:enhancement A potential new feature to be added, or an improvement to how we print something

Comments

@ExE-Boss
Copy link
Contributor

ExE-Boss commented Mar 29, 2019

Prettier 1.16.4

Playground link

{
	"parser": "markdown",
	"tabWidth": 4,
	"useTabs": true,

	/**
	 * `markdownHeadings` values:
	 * - `atx` (default)
	 * - `setext`
	 * - `setext-h1` (only `<h1>` uses the setext syntax)
	 */
	"markdownHeadings": "setext",
}

Input:

Setext Heading 1
================

Setext Heading 2
----------------

## ATX Heading 2

Output:

# Setext Heading 1

## Setext Heading 2

## ATX Heading 2

Expected behavior:

Setext headers are used:

Setext Heading 1
================

Setext Heading 2
----------------

ATX Heading 2
-------------

Preferably, I’d also like if there was an option to have only Heading 1 use the setext syntax, and the rest use the ATX syntax.

@ExE-Boss ExE-Boss changed the title Support setext headers in Markdown Support setext headings in Markdown Mar 29, 2019
@j-f1 j-f1 added lang:markdown Issues affecting Markdown status:needs discussion Issues needing discussion and a decision to be made before action can be taken type:option request Issues requesting a new option. We generally don’t accept these unless there is technical necessity. labels Mar 30, 2019
@brianary
Copy link

This is pretty important if you want the source Markdown/CommonMark/GFM text to be highly readable (a design goal of the language). ATX levels 1 & 2 don't exactly have much gravitas:

# Troubleshooting

## Setup

Lorem ipsum …

Sure, it's easier to parse, but that shouldn't be the driver of style.

Setext visually scans much more intuitively as a heading:

Troubleshooting
===============

Setup
-----

Lorem ipsum …

I'd advocate not just for the option, but for Setext to be the default header rendering.

@j-f1
Copy link
Member

j-f1 commented Sep 5, 2019

Looking at this again, I think an option would be unnecessary, but it would be OK if we preserved the style used in the original code.

@j-f1 j-f1 added type:enhancement A potential new feature to be added, or an improvement to how we print something and removed type:option request Issues requesting a new option. We generally don’t accept these unless there is technical necessity. labels Sep 5, 2019
@ExE-Boss
Copy link
Contributor Author

ExE-Boss commented Sep 5, 2019

Prettier currently preserves setext headings if they’re multi‑line, eg.:

Heading
[![Shields.io badge](https://img.shields.io/badge/Shields.io-badge-brightgreen)](https://shields.io)
=======

This is arguably worse than not preserving them at all, as it results in inconsistent formatting of headings.

@brianary
Copy link

brianary commented Sep 5, 2019

@j-f1 That seems pretty reasonable. I wish it would clean up all the code Pretty forced its opinion on from my team members for the last year or so, though. It's going to be a lot of cleanup. Going along with whatever's there does seem at odds with having a standard or a strong opinion, too.

@j-f1 j-f1 added help wanted We're a small group who can't get to every issue promptly. We’d appreciate help fixing this issue! and removed status:needs discussion Issues needing discussion and a decision to be made before action can be taken labels Jan 16, 2020
@Evpok
Copy link

Evpok commented Nov 11, 2021

If I read this and this correctly, there is not a lot of chance that preserving what is is there could be possible, since the parsers explicitly do not support keeping this information. So maybe allowing to configure the output style would be easier?

@brianary
Copy link

I've written what I'd consider an even-handed analysis of the available Markdown header styles that relates to this formatting question, whether opinionated or configurable.

@starball5
Copy link

@Zemnmez
Copy link

Zemnmez commented Jul 14, 2023

Would be really nice to have setext-style headings. I think they better reflect the intentions of Markdown to be readable both rendered and not rendered.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
help wanted We're a small group who can't get to every issue promptly. We’d appreciate help fixing this issue! lang:markdown Issues affecting Markdown type:enhancement A potential new feature to be added, or an improvement to how we print something
Projects
None yet
Development

No branches or pull requests

6 participants