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

Add Ability to Use Codeblock Language as Container Title #10808

Open
2 tasks done
hichemfantar opened this issue Jan 3, 2025 · 2 comments · May be fixed by #10809
Open
2 tasks done

Add Ability to Use Codeblock Language as Container Title #10808

hichemfantar opened this issue Jan 3, 2025 · 2 comments · May be fixed by #10809
Labels
feature This is not a bug or issue with Docusausus, per se. It is a feature request for the future.

Comments

@hichemfantar
Copy link
Contributor

hichemfantar commented Jan 3, 2025

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

type CodeBlock = {
  useLanguageAsTitle: boolean;
};

docusaurus.config.ts

    {
     themeConfig: {
       codeBlock: {useLanguageAsTitle: true},
     }
    }

Have you tried building it?

yes

https://github.com/hichemfantar/docusaurus-fork/tree/codeblock-language-as-title

Self-service

  • I'd be willing to contribute this feature to Docusaurus myself.
@hichemfantar hichemfantar added feature This is not a bug or issue with Docusausus, per se. It is a feature request for the future. status: needs triage This issue has not been triaged by maintainers labels Jan 3, 2025
@slorber
Copy link
Collaborator

slorber commented Jan 3, 2025

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:

  • Afaik only you requested it so far so we don't really know if there's user traction
  • It probably doesn't make sense to apply it by default for all languages, we need flexibility
  • We need a way to display "clean" language names, maybe not just "md" or "js"
  • It can be implemented in userland with swizzle or a remark plugin with greater flexibility

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 useLanguageAsTitle themeConfig would only be an unflexible shortcut doing exactly the same. I'd prefer to only add such shortcuts once traction is proven in the real world, and that we can compare how implementations converge to find out the best opinionated API.

Does it make sense?

@slorber slorber removed the status: needs triage This issue has not been triaged by maintainers label Jan 3, 2025
@hichemfantar
Copy link
Contributor Author

Thanks the in depth explanation! I'll try the plugin approach and report back.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
feature This is not a bug or issue with Docusausus, per se. It is a feature request for the future.
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants