godot-rust / godot-rust/book

Find or write mdbook plugin to have code blocks in tables

Open
#17 7 comments 0 reactions 0 assignees View on GitHub
tooling
Dominant language
CSS
Stars
54
Forks
74
PR merge metrics
No merged PRs in 30d

Description

## Problem

Neither Markdown dialect seems to support fenced code blocks in tables.
Something like this (here HTML):


GDScript
Rust


class_name MyClass

extends Node



#[derive(GodotClass)]

#[class(base=Node)]
struct MyClass;


In mdbook, it's possible to use raw HTML, but it's also very unreadable.
This is the source for the above. Yes, the line breaks need to be like that to avoid trailing/leading empty lines.

```html


GDScript
Rust


class_name MyClass

extends Node



#[derive(GodotClass)]

#[class(base=Node)]
struct MyClass;


```

## Possible solutions

With mdbook, the tag `` can be used for syntax highlighting instead of `

`.

We should research if there is an mdbook plugin achieving something similar, or write our own.

If we do it ourselves, it doesn't necessarily need to be generic and reusable. We could just start to support the above case and take it from there. Even something simple such as

```codetable left="gdscript" right="rust"

class_name MyClass
extends Node
---
#[derive(GodotClass)]
#[class(base=Node)]
struct MyClass;
```

could be transformed into the verbose HTML above.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by researching whether an mdBook plugin already supports fenced code blocks inside tables, using the raw HTML example and proposed `codetable` syntax in this issue as requirements. If no suitable plugin exists, define how the compact syntax should become readable HTML with syntax-highlighted Rust and GDScript blocks, then verify the rendered documentation output.

Written by the indexing model from the issue text.

Assessment

Tech stack
markdown, rust
Domain
documentation, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.