Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Create standard spec #53

Open
2 tasks
farnabaz opened this issue Oct 25, 2022 — with Volta.net · 1 comment
Open
2 tasks

Create standard spec #53

farnabaz opened this issue Oct 25, 2022 — with Volta.net · 1 comment
Labels
documentation Improvements or additions to documentation

Comments

Copy link
Collaborator

farnabaz commented Oct 25, 2022

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
@atinux atinux added the documentation Improvements or additions to documentation label Oct 25, 2022 — with Volta.net
@nobkd
Copy link

nobkd commented Sep 29, 2023

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

No branches or pull requests

3 participants