-
-
Notifications
You must be signed in to change notification settings - Fork 8.7k
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
Add Ability to Use Codeblock Language as Container Title #10808
Comments
I agree it can be useful in some cases to display the language, but I'm not sure this option would be that useful in Docusaurus for a few reasons:
Considering it can be implemented in userland easily, I'd prefer to see production implementations in userland first, proving that there's real traction, before adding a first-class option in Docusaurus. Once we have a few production sites using it, only then it's worth adding to Docusaurus. In general, I prefer focusing on shipping primitives that allow you to compose those primitives the way you want with great flexibility. We have md code language, and we have md code meta string support for a title attribute. You can achieve what you want by combining these 2 primitives using your own custom code and custom rules. Here's a remark plugin example: const mapping = {
js: "JavaScript",
ts: "TypeScript",
}
function languageAsTitleRemarkPlugin() {
return async (root) => {
const {visit} = await import('unist-util-visit');
visit(root, 'code', (node) => {
if (!node.meta && mapping[node.lang]) {
node.meta = `title="${mapping[node.lang]}"`;
}
});
};
} It's more code, but also more flexible. Adding a Does it make sense? |
Thanks the in depth explanation! I'll try the plugin approach and report back. |
Have you read the Contributing Guidelines on issues?
Description
Currently, Docusaurus renders the language specified in a codeblock as part of its syntax highlighting, but it doesn't allow using the language as the container title. This proposal suggests adding an option to display the codeblock's language as the title of the container for improved clarity and user experience.
This can be a global boolean setting in the Docusaurus config file where the codeblock component will always fallback to the language if a title isn't specified.
Has this been requested on Canny?
https://docusaurus.io/feature-requests/p/add-ability-to-use-codeblock-language-as-container-title
Motivation
When documenting code examples, it's often helpful to explicitly label the codeblocks with their language for better readability and context. While custom titles can be added using the title attribute in fenced codeblocks, it would be beneficial to have a built-in feature that automatically uses the language as the container title.
This is also beneficial when working around this use case https://github.com/DavidAnson/markdownlint/blob/v0.36.1/doc/md014.md where you want to remove the
$
sign to make copy pasting more convenient and allow the user to understand that the code block is a shell command.it works well for any language as the user can quickly figure out what language he's reading.
API design
docusaurus.config.ts
Have you tried building it?
yes
https://github.com/hichemfantar/docusaurus-fork/tree/codeblock-language-as-title
Self-service
The text was updated successfully, but these errors were encountered: