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

docs: [RFC] Configuring File Name from Block Meta #230

Open
wants to merge 3 commits into
base: main
Choose a base branch
from

Conversation

JoshuaKGoldberg
Copy link

Per #226 (comment), this is a mini-RFC based on roughly half of the design format from https://github.com/eslint/rfcs. Sending as a PR so we can make comment threads per-line and see a commit history.

@eslint-github-bot
Copy link

Hi @JoshuaKGoldberg!, thanks for the Pull Request

The pull request title isn't properly formatted. We ask that you update the pull request title to match this format, as we use it to generate changelogs and automate releases.

  • The commit message tag wasn't recognized. Did you mean "docs", "fix", or "feat"?
  • There should be a space following the initial tag and colon, for example 'feat: Message'.
  • The first letter of the tag should be in lowercase

To Fix: You can fix this problem by clicking 'Edit' next to the pull request title at the top of this page.

Read more about contributing to ESLint here

It only specifies syntax like <code>\`\`\`jsx live style={{border: '1px solid red'}}</code>

This RFC chooses `title` over alternatives such as `filename`.
`title` appears to be the closest to a "popular" choice in existing projects today.
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

cc @Josh-Cena from #208 - this looks like something you might have context / opinions on? 😄

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Mmm, I don't know much outside of Docusaurus/MDN markdown, and the two projects have exactly disjoint sets of meta attributes...

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks like most of the linked examples actually use filename. Which ones use title?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Docusaurus does.

I'll also note that I've since learned about Expressive Code through Astro Starlight. It uses title as a manual prop name: https://expressive-code.com/key-features/code-component/#title

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Given that, I don't think using title is a good idea. filename seems like a safer choice. We could also do eslint-filename as a completely safe choice, assuming no Markdown parser will balk at unknown attributes.

(We could also use filename unless eslint-filename is present.)

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't follow. Docusaurus is by far the most popular solution out of these. Is there a reason you're not fond of title for safety?

Personally, I actually do think filename makes more sense as a technical descriptor. "Title" to me reads as a display title, which isn't always the same as the file name. So I suppose I'm asking more out of thoroughness, not disagreement.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Docusaurus is just one use case for Markdown, producing online documentation, but that's not the only use case. I use Markdown to write books and blog posts, and I often feed that Markdown into different tools (including this one).

So, I'm looking at this from a general "what would most people writing Markdown expect?" perspective. This plugin needs to consider the whole universe of Markdown use cases.

@JoshuaKGoldberg JoshuaKGoldberg changed the title RFC: Configuring File Name from Block Meta docs: [RFC] Configuring File Name from Block Meta Dec 4, 2023
Copy link
Member

@nzakas nzakas left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for putting this together, and sorry for the delay (as I mentioned, v9 swallowed a lot of time).

This looks like a rational proposal to me. Only outstanding question I have is about title vs. filename (see inline). I suppose another option would be to support both? (and if both are present, just take the first one?)

It only specifies syntax like <code>\`\`\`jsx live style={{border: '1px solid red'}}</code>

This RFC chooses `title` over alternatives such as `filename`.
`title` appears to be the closest to a "popular" choice in existing projects today.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks like most of the linked examples actually use filename. Which ones use title?

@JoshuaKGoldberg
Copy link
Author

I asked Docusaurus about the decision to use title: facebook/docusaurus#10033.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
Status: Implementing
Development

Successfully merging this pull request may close these issues.

3 participants