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

feat(markdown): add title support for code blocks (close #1277) #1456

Merged
merged 5 commits into from
Dec 31, 2023

Conversation

nruffing
Copy link
Contributor

Before submitting the PR, please make sure you do the following

  • Read the Contributing Guidelines.
  • Provide a description in this PR that addresses what the PR is solving. If this PR is going to solve an existing issue, please reference the issue (e.g. close #123).

What is the purpose of this pull request?

  • Bug fix
  • New feature
  • Documentation update
  • Other

Description

Add support for being able to set a title for code blocks (e.g. a filename).

In case the data-ext attribute was being used for something else in a theme I added a new data-title attribute for the title and its value falls back to be the same as data-ext if an explicit title is not specified.

I opted to use enclose the title in < and > instead of square brackets so it would also easily work with the import code plugin which is already using square brackets.

Example

```ts <config/foo.ts> {1,2}:no-line-numbers
const foo = 'foo'

function bar () {
  return 1024
}
```

Tests have also been updated.

If we like this approach I can create a PR in theme-default to change the css to pull from the data-title attribute and update the docs.

closes #1277

Screenshots

Before

After

@meteorlxy
Copy link
Member

meteorlxy commented Dec 27, 2023

Any reference of the [] and <> of other markdown extensions? I think it would be better to use a commonly used mark so that users could migrate from other framework to vuepress with ease (and vice versa 😅 )

@nruffing
Copy link
Contributor Author

Here are some examples I found with some quick research. Based on this I could be on board with a key/value syntax like title="config/foo.ts".

fenceparser

```ts twoslash {1-3, 5} title="Hello, World"
```

MyST

```{code} yaml
:filename: myst.yml
project:
  title: Showing Filenames in code-blocks
```

Docusaurus

```jsx title="/src/components/HelloCodeTitle.js"
function HelloCodeTitle(props) {
  return <h1>Hello, {props.name}</h1>;
}
```

rehype-code-titles

```typescript:lib/mdx.ts
```

@meteorlxy
Copy link
Member

Agree with the key-value implementation. It's also a more extendable syntax

@nruffing
Copy link
Contributor Author

Sounds good. I will make those changes.

@meteorlxy meteorlxy merged commit 706a427 into vuepress:main Dec 31, 2023
33 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Add title support for code blocks
3 participants