Friendly doc Helpers

[QingWei-Li]

• Considering this as well Friendly doc Helpers #413 (comment). ( @jhildenbiddle 's thoughts ?)

---

docsify extends Markdown syntax to make your documents more readable.

> [!] **Time** is money, my friend!

In Markdown

[!] Time is money, my friend!

In docsify

---

> [?] _TODO_ unit test

In Markdown

[?] TODO unit test

In docsify

---

New helpers

> [v] Good

> [x] Bad

> [detail] summary
> detail detail deatail
> xxxx

[jhildenbiddle]

Friendly request for code support in <details> elements. 😄

> [details] Sample Code
> ```javascript
> console.log('foo');
> ```

[jhildenbiddle]

Three helper-related items worth mentioning:

1. Blockquote helpers should support nested block-level elements

Consider how generic markdown supports multiple paragraphs in a single blockquote:

> Paragraph 1
>
> Paragraph 2

HTML output:

<blockquote>
  <p>Paragraph 1</p>
  <p>Paragraph 2</p>
</blockquote>

Unfortunately, the existing "important content" and "general tips" do not support nested block-level elements properly:

?> Paragraph 1
?>
?> Paragraph 2

HTML output:

<p class="tip">Paragraph 1
!&gt;
!&gt; Paragraph 2</p>

The correct HTML output should be:

<div class="tip">
  <p>Paragraph 1</p>
  <p>Paragraph 2</p>
</div>

2. Docsify-specific markdown

Markdown is an environment-agnostic format. Markdown used with docsify will likely be viewed, edited, and previewed outside of docsify by site devs and content authors. Consideration should be given to the experience of working with docsify-specific markdown in these environments, not just how it will render in the final docsify site.

From the original markdown project page:

"Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML).”

"The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions."

Docsify helper syntax should be simple, consistent, and as unobtrusive as possible when authoring content and reading rendered content on a docsify site or any other environment (GitHub, code editor, markdown preview, etc).

For example, consider how the current v4 syntax for the "important content" and "general tip" helpers compares to the new v5 syntax proposed by @QingWei-Li:

Current v4 syntax rendered here on GitHub:

?> General Tip

!> Important Content

Proposed v5 syntax rendered here on GitHub:

[?] General Tip

[!] Important Content

The new format allows the "General Tip" and "Important Content" blocks to be visually distinct from the surrounding text content when rendered outside of docsify (like here on GitHub), and the text-as-icon indicators don't significantly impact readability. This is (IMHO) much better than the previous syntax, which to my eyes looked like broken or unprocessed markdown.

I mention this as good advise for helper-related v5 discussions in general, and because it relates directly to the next item...

3. Blockquotes-as-containers vs. alternate approaches

Markdown's blockquote syntax is a convenient way to render container elements, but this syntax may not be the best mechanism for all helpers that require a container element. Specifically, some content (like the "Important content" and "General tip" blocks) look fine when rendered as blockquotes outside of docsify, but others do not.

For example, consider how a <details> helper that leverages markdown's blockquote syntax will render outside of a docsify site:

> [details ':open'] Summary / Title
> 
> Some Text.
>
> ```javascript
> console.log('foo');
> ```

Rendered here on GitHub:

[details ':open'] Summary / Title

Some Text.

console.log('foo');

Yeesh. Not good.

I wrestled with this same issue while developing docsify-tabs: how can I indicate tab titles and their associated content in markdown without adding a non-standard, docsify-specific syntax that will look terrible when rendered outside of docsify?

The solution I came up with was to use HTML comments (which are valid markdown and properly hidden when markdown is rendered) to serve as the start and end of a container, then use standard markdown elements (like headings) to serve special purposes when placed between those comments.

Here is the example provided in the Usage section of the docs:

<!-- tabs:start -->

#### **English**

Hello!

#### **French**

Bonjour!

#### **Italian**

Ciao!

<!-- tabs:end -->

Rendered as HTML by docsify-tabs:

Rendered as markdown here on GitHub:

---

English

Hello!

French

Bonjour!

Italian

Ciao!

---

Perfect. No docsify-specific markdown for formatting visible when rendered outside of docsify. This same approach could be used for a <details> helper as well:

<!-- details:start -->

#### Summary / Title

Some Text.

```javascript
console.log('foo');
```

<!-- details:end -->

Rendered as HTML:

---

Summary / Title

Some Text.

console.log('foo');

---

Rendered as markdown here on GitHub:

---

Summary / Title

Some Text.

console.log('foo');

---

With this format, the opening comment can be used to set options using HTML-like attributes that docsify can detect but other markdown parsers (like GitHub) will ignore. For example, this could allow setting the open attribute on a <details> element:

<!-- details:start open -->

For other helper elements, it could allow specifying both standard HTML attributes (id, class, style, etc.) or helper-specific attributes:

<!-- helper:start id="my-id" class="my-class" style="background: red;" helper-specific="abc123" -->

Hope this was helpful, and apologies for the lengthy post. Just wanted to get these three topic covered in one place.

Thanks!