Create standard spec

[farnabaz]

Markdown Components

1. Inline Components

Inline components can be defined in everywhere inside the content. The inline component's syntax:

A single paragraph with in inline :component[Label]{key=val}

Note that inline component should come after or before some contents. Otherwise, they will be treated as Lead Block Components.

If you want to use an inline component followed by specific characters like -, _, or :, you can use a dummy props specifier after it.

How to say :hello{}-world in Markdown

2. Block Components

Block components contain further blocks. The proposed syntax for block components is:

::name{key=val}
---
key: val
---
contents, which are sometimes further block elements
::

2.1. Nesting

Analogous to fenced code blocks, an arbitrary number of colons greater or equal to two could be used as long as the closing line is longer than the opening line. That way, you can even nest blocks by using successively more colons for each containing block.

::name{key=val}
---
key: val
---

:::foo{name=foo}
contents, which are sometimes further block elements
:::

::

Nested blocks can also become distinguishable using indention.

::name{key=val}
---
key: val
---

  :::foo{name=foo}
  contents, which are sometimes further block elements
  :::

::

2.2. Sections (Slots)

Block components can separate their children into different sections. Look at these sections and Vue's slots that can be rendered separately in different palaces.

::name{key=val}
---
key: val
---

Default section(slot): everything you write inside a block component will concider as `default` section.

#named-section

Everything comes after `#SECTION_NAME` will goes into another section.

#anoter-section

You can have as much sections as you want.

::

3. Leaf Block Components

The syntax for leaf block components:

:name{key=val}

To be recognized as a block component, leaf block should appear in the begging of the like without any siblings. Otherwise, they will be treated and inline components.

Note that leaf block components can't have more than one colon in their definitions. Blocks with more colons requires an ending line.

Paragraph 1
            <~~ Like paragraphs, ensure that you have and empty line before component
:component
            <~~ Like paragraphs, ensure that you have and empty line after component
Paragraph 2

4. Span

Span syntax can be used to pass attributes to part of content.

hello [world]{.myClass}

5. Attributes

5.1. Links

[Links](/href){.my-class rel="noopener"}

5.2. Images

![Alt](/image.jpg){.my-class}

5.3 Strong

Hello **World**{.my-class}

5.4. Italic

Hello __World__{.my-class}

5.5. Inline Code

The shortcut is `CMD + K`{.my-class}

5.6. Inline/Block Component

Hello :world{key=value}

::block-component{key=value}
The block content
::

:leaf-component{key=value}

5.7. Block Components reach attributes

Block components accept special form of attributes, similar to markdown front-matter syntax.

::name
---
key: value
tags:
  - tag1
  - tag2
object1:
  field1: value
  field2: value
---
::

6. [TBD] Formatting & Spacing

With defining a set of rules, we can format the content in a consistent way. MDC could have it's own linter and prettier to format the content in a consistent way.

• How to deal with spacing, the correct way to creating line breaks, new paragraphs and ...
• How to pass props to block components. For example if you pass less than two props and all are string you can use {} syntax, otherwise they should define ---/n.../n--- section

[nobkd]

Just linking ideas about unwrapping of (p) tags in slots: antfu/markdown-it-mdc#2 (comment)