eosnetworkfoundation / docsgen

Scripts for creating docs.eosnetwork.com pulls from various eos nf repos and builds static HTML to power website
Other
3 stars 0 forks source link

Support for Info and Warning labels/tags #15

Closed iamveritas closed 1 year ago

iamveritas commented 2 years ago

We need support for these custom markups below:

[[info | Implementation location]] [[warning | Implementation location]] [[caution | Implementation location]] [[danger | Implementation location]]

When they are present in an md file the text should render differently (color and background) for each of them.

ericpassmore commented 2 years ago

Need to update the syntax for these. The new syntax is as follows.

:::info Implementation location :::

We should transform this in the code first because I'm not sure if you will like the new style.

Also supported note, tip, caution, danger https://docusaurus.io/docs/markdown-features/admonitions

ericpassmore commented 2 years ago

new script created ericpassmore-working branch to fix this scripts/process_admonitions.py

will merge later

ericpassmore commented 2 years ago

One more case, in the example below need to consume the 'pipe' between ]] | end of section and start of text. May want to move text till end of line into info block

[[info | Access Node]] | A local or remote EOSIO access node running nodeos is required for a client application or smart contract to interact with the blockchain.

lparisc commented 2 years ago

One more case, in the example below need to consume the 'pipe' between ]] | end of section and start of text. May want to move text till end of line into info block

[[info | Access Node]] | A local or remote EOSIO access node running nodeos is required for a client application or smart contract to interact with the blockchain.

There's another case: there might be multiple vertical lines with content:

[[info | Access Node]]
| content 1
| content 2
...

Each content 1, 2, etc. would render as a separate paragraph within the callout box.

Personally, I'd prefer working with the new codeblock syntax. I find it more friendly.

lparisc commented 1 year ago

Reopening since the above case was not handled, which causes some callouts to not render correctly:

source: https://github.com/eosnetworkfoundation/docs/blob/main/docs/03_tutorials/10_bios-boot-sequence.md#154-restart-genesis-node-with-replay

view: https://docs.eosnetwork.com/docs/latest/tutorials/bios-boot-sequence#154-restart-genesis-node-with-replay

@ericpassmore

ericpassmore commented 1 year ago

Hmm, this syntax is out of spec. Can you provide more info. There are pipes | in the content. What is the expected rendering for those symbols. Ok I see the info above each | a separate paragraph.

ericpassmore commented 1 year ago

The parsing is getting hairy. Sometimes a line following an admonition should not be part of the notice. Example

[[info]] | this is another inline body section.
Don't put me in admonition!!

Sometimes the line following an admonition should be part of the notice. Example

[[info | The genesis node is defined by the following:]]
| - Bears the name `eosio`
| - Produces blocks
| - Listens for HTTP request on 127.0.0.1:8888
| - Listens for peer connections requests on 127.0.0.1:9010

There is no closing character for admonition in the old format. Therefore I plan to support multi-line admonitions that start with |. I'm not going to support other scenarios. If other cases arise the markdown will need to be altered to match the docusaurus admonition markdown standard.