search

facebook / docusaurus

Easy to maintain open source documentation websites.
https://docusaurus.io
MIT License
55.65k stars 8.34k forks source link

Details / Summary html component #2924

Closed maximousblk closed 3 years ago

maximousblk commented 4 years ago

🚀 Feature

A callout that functions like the HTML details tag

Have you read the Contributing Guidelines on issues?

yes

Motivation

I was trying to put logs in my documentation and it was not ideal because I had to use HTML for all the content inside the details tag

Pitch

Syntax (nothing new):

:::details This is the summary of the content inside this callout

This

is

the

the

very

long

content

:::
slorber commented 4 years ago

Hi,

There are many example of details/summary view on this D2 website: https://react-typescript-cheatsheet.netlify.app/docs/basic/getting-started/default_props

MDX currently has some limitations, it does not have proper support for "markdown interleaving"

The trick is to skip lines around your details content, and MDX will understand that the inner content is MDX, and you'd be able to use MDX syntax.

https://raw.githubusercontent.com/typescript-cheatsheets/react-typescript-cheatsheet/master/docs/basic/getting-started/default-props.md

Anyway, I wouldn't be against having first-class support for this kind of feature.

Also think we could style it a bit better, as I think it can be hard to see the "end" of the details view.

There are many advanced exemples possible here, some are lightweight / CSS only: https://freefrontend.com/html-details-summary-css/ https://codepen.io/frogmcw/pen/deqRwa

Can be an issue for MLH

@yangshun could this be in Infima?

maximousblk commented 4 years ago

I have prepared a demo for what it should look like. [code]

Preview:

admonitions

It is based on the proposed design for #2930

slorber commented 4 years ago

that looks good to me :)

FocalChord commented 4 years ago

@slorber Is it alright if I take up this issue to work on?

slorber commented 4 years ago

Hi @FocalChord

I think this should be done in Infima, so I'm not against but we should see first with @yangshun if you can have access

slorber commented 3 years ago

@maximousblk will implement this in https://github.com/facebook/docusaurus/issues/2924

Do we really need to have a special syntax, or using details/summary tags with MDX is good enough?

maximousblk commented 3 years ago

it would be better to keep it consistent with other admonitions but it's fine if there's a reason to not do that.

slorber commented 3 years ago

We can add that :::details syntax but it would be a different feature as it requires extending the markdown syntax with remark. We may be able to leverage our existing admonitions plugin to do so.