search

vuepress / docs

VuePress Documentation
https://vuepress.vuejs.org
MIT License
21 stars 82 forks source link

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

Closed polarathene closed 6 days ago

polarathene commented 1 month 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 1 month 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 1 month 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 1 month 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 4 weeks 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 1 week 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.