CodeBlocks Table for further Description of the code

[dschiller]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Description

As i am working with Docusaurus for the last two days i wonder if there is no need to have Tables to further describe Code in CodeBlocks. What i did is adding a Custom CSS styled Table below my CodeBlocks to describe what the Code in the CodeBlocks do.

docs/Knowledgebase/documentation/frameworks/docosaurus/index.mdx

<Tabs>
    <TabItem value="component" label="Component" default>
        <CodeBlock language="jsx" showLineNumbers title="docs/Knowledgebase/_components/git/clone-repository.mdx">
{`import CodeBlock from '@theme/CodeBlock';

{/* Renders a Clone repository shell Snippet
    *
    * Properties:
    *     name: The Name of the Repository
    *     repositoryName: The GitHub Repository name
    */}

- Clone **{props.name}** via

<CodeBlock language='shell'>
{${'`'}git clone git@github.com:me/\${props.repositoryName}.git .${'`'}}
</CodeBlock>`}
        </CodeBlock>
        <table className="CodeBlockTable">
            <tr>
                <td>**File**</td>
                <td>It doesn't need to be the `_components` folder, you can use any folder structure you want. We use
                `_components` to understand that this folder contains our MDX Components and the underscore (`_`)
                let us see this Components folder as the first folder, as our IDE sorts folders in alphabetically order.</td>
            </tr>
            <tr>
                <td>**1**</td>
                <td>`CodeBlock` comes wit **Docusaurus** and enables us to use
                [Code blocks](https://docusaurus.io/docs/markdown-features/code-blocks)</td>
            </tr>
            <tr>
                <td>**3 - 8**</td>
                <td>DocStrings, to describe the Component's function and it's used Properties</td>
            </tr>
            <tr>
                <td>**10**</td>
                <td>`{props.name}` is connected with the `name` Property in the `<CloneRepository name="Any Name" />` Component.
                It has to be `props` to access Component Properties. But you can use any name for your Properties. So
                `name` could also be `gitName`. Dashes like in `git-name` are not allowed.</td>
            </tr>
            <tr>
                <td>**13**</td>
                <td>To be able to access Component Properties in Code blocks we need to wrap the Code block's content inside
                `{``}`. And we need to add the `$` sign in front of the substitution like in `${props.repositoryName}`. This let us access the `repositoryName`
                Property from the `<CloneRepository repositoryName="Any Repository Name" />` Component.</td>
            </tr>
        </table>
    </TabItem>
...

The CSS code i use is

src/css/custom.css

:root {
...
  --code-block-table-border-color: #bbb;
  --code-block-table-first-td-color: #ccc
}
...
[data-theme='dark'] {
...
  --code-block-table-border-color: #333;
  --code-block-table-first-td-color: #000
}
...
/* A special Table for CodeBlock descriptions */

[data-theme='dark'] .CodeBlockTable table,
[data-theme='dark'] .CodeBlockTable th,
[data-theme='dark'] .CodeBlockTable td,
[data-theme='dark'] .CodeBlockTable tr {
  background-color: #111 !important;
}

[data-theme='light'] .CodeBlockTable table,
[data-theme='light'] .CodeBlockTable th,
[data-theme='light'] .CodeBlockTable td,
[data-theme='light'] .CodeBlockTable tr {
  background-color: #eee !important;
}

.CodeBlockTable {
  border-collapse: separate;
  border-spacing: 0 1px;
}

/* >> Table Paddings */

.CodeBlockTable tr:first-of-type td:first-of-type {
  padding-top: 15px !important;
}

.CodeBlockTable tr:first-of-type td {
  padding-top: 15px !important;
}

.CodeBlockTable tr td:first-of-type {
  padding-left: 15px !important;
}

.CodeBlockTable tr td:last-of-type {
  padding-right: 15px !important;
}

.CodeBlockTable tr:last-of-type td {
  padding-bottom: 15px !important;
}

/* << Table Paddings */

/* >> Table Borders Radius */

.CodeBlockTable tr:first-of-type td:first-of-type {
  border-radius: 10px 0 0 0;
}

.CodeBlockTable tr:first-of-type td:last-of-type {
  border-radius: 0 10px 0 0;
}

.CodeBlockTable tr:last-of-type td:first-of-type {
  border-radius: 0 0 0 10px;
}

.CodeBlockTable tr:last-of-type td:last-of-type {
  border-radius: 0 0 10px 0;
}

/* << Table Borders Radius */

/* >> Table Borders */

.CodeBlockTable tr:first-of-type td:first-of-type {
  border-left: 1px dashed var(--code-block-table-border-color) !important;
  border-top: 1px dashed var(--code-block-table-border-color) !important;
}

.CodeBlockTable tr:first-of-type td:last-of-type {
  border-right: 1px dashed var(--code-block-table-border-color) !important;
  border-top: 1px dashed var(--code-block-table-border-color) !important;
}

.CodeBlockTable tr:last-of-type td:first-of-type {
  border-left: 1px dashed var(--code-block-table-border-color) !important;
  border-bottom: 1px dashed var(--code-block-table-border-color) !important;
}

.CodeBlockTable tr:last-of-type td:last-of-type {
  border-right: 1px dashed var(--code-block-table-border-color) !important;
  border-bottom: 1px dashed var(--code-block-table-border-color) !important;
}

.CodeBlockTable tr td:first-of-type {
  border-left: 1px dashed var(--code-block-table-border-color) !important;
}

.CodeBlockTable tr td:last-of-type {
  border-right: 1px dashed var(--code-block-table-border-color) !important;
}

/* << Table Borders */

.CodeBlockTable tr td:first-of-type {
  text-align: right;
  text-wrap: nowrap;
}

.CodeBlockTable tr td:first-of-type {
  background-color: var(--code-block-table-first-td-color) !important;
}

.CodeBlockTable tr td:first-of-type {
  padding-right: 10px !important;
}

.CodeBlockTable table, th, td, tr {
  border: 0px solid transparent !important;
  vertical-align: top;
}

.CodeBlockTable th, td {
  padding: 5px !important;
}

This all results in the following render, and i wonder that this descriptive Code Table couldn't be part of the Docusaurus default, to support CodeBlocks.

In addition it would be nice when hovering any row in the table that the corresponding line in code will be highlighted too to see the connection.

Has this been requested on Canny?

No response

Motivation

i can not say if that has been requested by a lot of users. This was my first intuition i got, when working with CodeBlocks in our Documentation, and i believe it is kinda mandatory for others that work with code a lot. And the motivation is, to support CodeBlocks which makes a lot of sense to me as reading code can lead to many interpretations and adding some notes to it is very helpful in my opinion.

API design

i do not know how the API design could look like.

Have you tried building it?

Yes i tried building it, see the above examples.

Self-service

• I'd be willing to contribute this feature to Docusaurus myself.

[slorber]

I believe this is a duplicate of #10108