search

vuepress / docs

VuePress Documentation
https://vuepress.vuejs.org
MIT License
28 stars 100 forks source link

[Bug report] Improve visibility / discovery of the "Custom Container" (`:::`) syntax feature #29

Closed polarathene closed 2 months ago

polarathene commented 4 months ago

Description

Your docs page doesn't seem to mention the syntax for admonition/aside/alert (name varies based on docs generator):

image

I am referring to the Tip section at the bottom there, where inspecting the source reveals the syntax:

https://github.com/vuepress/docs/blob/3b0eefefe3bc43f24aec9621725943b70da44434/docs/guide/markdown.md?plain=1#L20-L28

It's a common feature that I assume is available by default with VuePress (never used the project myself), so might be worth documenting. If it is documented somewhere I had trouble identifying where.

EDIT: I found it documented separately for the theme itself as "Custom Container" markdown syntax: https://ecosystem.vuejs.press/themes/default/markdown.html#custom-containers

Since your docs are showing that feature off quite a bit, might be worth referencing that more directly to the audience that is likely to be interested in the feature (searching for ::: or similar common words for the syntax/type doesn't really help).

Mister-Hope commented 3 months ago

Can you open a pr from a user sight of view? Only en is ok, if we think this is good, I will sync zh docs.

polarathene commented 3 months ago

Can you open a pr from a user sight of view?

No sorry, I'm not a VuePress user.

I reported this when I came across it while writing this reply on another project. I link to the equivalent feature in other doc generators, you could reference those.

meteorlxy commented 3 months ago

It used to be in the core in v1, but it would require all themes to implement styles for custom containers, which is not necessary, so we moved it into theme scope. But yes, as it's a widely used syntax, we may consider integrating it into core again, or move the docs back to core (just like the markdown code extensions)

github-actions[bot] commented 3 months ago

This issue is marked as stale because it has not had recent activity. Issues marked with stale will be closed if they have no activity within 7 days.

github-actions[bot] commented 2 months ago

This issue is marked as stale because it has not had recent activity. Issues marked with stale will be closed if they have no activity within 7 days.