oasisprotocol / oasisprotocol/docs

Use standard markdown syntax for doccards

Open
#215 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

p:2
Dominant language
TypeScript
Stars
15
Forks
46
Avg merge
1d 21h
Merged PRs (30d)
1

Description

Currently, in order to use doccards you need to write a .mdx file, import and use DocCard or DocCardList react components along with our findSidebarItem in docUtils.js. This is quite some boilerplate code for oasis-core, oasis-sdk and other repositories which in general only include plain markdown files. Since there is no standard markdown syntax for doccards, we should still strive to use standard markdown so it is valid outside of docusaurus.

I suggest we use standard markdown syntax for doccards and then wrap it with actual components using remark as follows.

Single-line doccard:

@[doccard](../../some/file.md)

would be transformed into

<DocCard item={findSidebarItem("/general/some/file")} />

And for doccard list:

@doccardlist:

- ../../some/file1.md
- ../some/file2.md
- some/file3.md

would be transformed into:

<DocCardList items=[{
  findSidebarItem('/general/some/file1'),
  findSidebarItem('/general/network/some/file2'),
  findSidebarItem('/general/network/settings/some/file3'),
]} />

Potential issues:

  • if the doccard syntax above appears inside .md file (and not .mdx), will docusaurus want to compile <DocCardList> syntax inside "plain" .md file?
  • the @[doccard](some/link) will show doccard as text on the link. If there are multiple doccards one after another, that will be pretty nondescriptive

Alternatives:

  • Instead of using doccard literal, perhaps just placing @ in front of the link is sufficient? Or some other magic symbol, like ! or =? e.g. =[../../some/file.md]=
  • Maybe we could unify doccard and doccard list, so that if there is a single item, use doccard and for more items, doccardlist? Is there a way to set the number of doccards per row?
  • Check vuepress1&2, if they provide any better markdown syntax for doccards.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reading docUtils.js and the existing DocCard and DocCardList usage in .mdx files, then inspect how remark is integrated into the documentation pipeline. Compare the proposed single-card and list syntaxes, including their behavior in .md files, and resolve which syntax should be supported before implementing it. Done means plain Markdown can express doccards and the remark transformation produces the expected components.

Written by the indexing model from the issue text.

Assessment

Tech stack
markdown, react, typescript
Domain
documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.