search

amazingrando / blades-in-the-dark-srd-content

SRD for the Blades in the Dark RPG
https://bladesinthedark.com
175 stars 62 forks source link

rewrite in asciidoctor? #5

Open zeddee opened 5 years ago

zeddee commented 5 years ago

I noticed that there are a few todos e.g. @TODO add Action Roll table p21 in line 359 of Blades-in-the-dark-SRD.md that are difficult to get done in markdown because it just doesn't have the tools to get it done. I've worked with a few other markdown-ish languages that have better tooling, and asciidoctor looks like it may fit the needs of this doc.

i can start to try to convert the doc to asciidoctor, and then work on the todos.

plus, this repository is missing build/contribution instructions; i could do that too

david-in-perth commented 5 years ago

AsciiDoc vs. Asciidoctor

To clarify: AsciiDoc is the name of the markup format, Asciidoctor is the name of a toolchain for converting AsciiDoc content into other formats.

Tables in Markdown

For the record, if it's just simple tables that are needed, you can embed tables in a Markdown document. To comply with original Markdown / CommonMark, you would have to use a standard HTML <table> element. There is also special syntax for tables in markdown variants like GitHub/GitLab Flavoured Markdown (as shown below).

Markdown has its issues and limitations, so AsciiDoc might indeed be a better fit, but it's worth mentioning that these other options exist.

Example table in GitHub Flavoured Markdown

Markdown Variant Supports Tables?
Original Markdown / CommonMark yes, with HTML <table> tags
GitHub / GitLab Flavoured Markdown yes, with extension syntax

GFM Source:

| Markdown Variant | Supports Tables? |
| ---- | ---- |
| Original Markdown / CommonMark | yes, with HTML `<table>` tags |
| GitHub / GitLab Flavoured Markdown | yes, with extension syntax |
OldManUmby commented 2 years ago

I have submitted a pull request which fixes a lot of issues. Cross your fingers they Merge.