mirror of
https://github.com/docsifyjs/docsify.git
synced 2025-12-08 19:55:52 +00:00
77d93fae78
Style updates: - New "core" theme serves as base for all other themes (official and third-party) - New CSS custom properties for simplified customization of "core" theme **Note:** List of available properties will be made available in documentation by embedding soruce CSS in docs after merge. Merge is required because embedded CSS needs to be in `main` branch. For now, see `_vars.css` and `_vars-advanced.css` for details. - New theme "add-ons" modify core theme properties and/or add custom declarations as needed. - New Prism.js theme support - New configurable sidebar toggle design - New typography defaults to system sans-serif and monospace fonts instead of relying on external web font. - New "Core Dark" theme addon provide dark theme styles. Can optionally be applied based on operating system's light/dark setting using `@media` attribute on `<link>` element. - New "Vue" theme addon. Closely replicated popular v4 theme while allowing for v5 enhancements. - New CSS class names available for adding loading indicators, adding sidebar expand/collapse icons, adding sidebar group styles, clamping sidebar links to a single line with ellipses, and changing the sidebar toggle icon. - New auto-generated gradient background for cover page (ensure gradient hue is > 50 degree apart, use OKLCH color if supported, randomize grandient angle, reduce brightness in dark mode) - New button styles (basic, primary, secondary) - New form element styles (text input, radio, checkbox, ) - New "callouts" (previously "important" and "tip" helpers) - New default syntax highlighting theme (from [docsify-themeable](https://jhildenbiddle.github.io/docsify-themeable/)) - New auto-generated theme color shade and tint colors - New auto-generated monochromatic color palette - New form element styles (fields, legend, text input, text area, checkbox, radio, toggles, and select) - New "headerless" tables - New `kbd` styles - New task list style - New merged navbar styles (consistent with sidebar nav styles) - New search plugin styles and keyboard shortcut indicators - Add ability restore previously focused content element after hiding sidebar - Add "focus trap" when sidebar is visible on mobile (accessibility) - Add ability for sidebar links to wrap by default (previous single-line w/ ellipsis display available as CSS class on `<body>` option) - Add sidebar `page-link`, `group`, and `group-title` CSS classes to sidebar markup. - Add reduced motion media query to set all animation/transition timings to zero - Update Google Font imports (use new variable vs older fixed width fonts) - Update primary/secondary button order on coverpage (primary should be first) - Fix missing merged navbar when loading at desktop resolution then resizing to mobile - Fix inverted open/close sidebar visibility state at desktop/mobile resolutions - Fix overflow setting to prevent clipping of element focus ring - Fix safe area inset margins on mobile in landscape orientation - Fix inverted "tip" and "warn" class names - Fix scroll padding to prevent headers from touching top edge of viewport when scrolled to - Remove Stylus dependency (now using only PostCSS) - Remove legacy themes "Buble", "Dark", "Dolphin", and "Pure". Documentation updates: - New "UI Kit" page showcasing all elements styled by Docsify - Update "Quick Start" page template - Update "Adding pages" page with information on how to properly create sidebar group titles and navbar drop-down menus - Update "Themes" page with theme and class toggles - Update "Configuration" page with deprecation warnings for `themeColor` and `topMargin` - Move "Edit Page" link to footer - Remove [docsify-themeable](https://jhildenbiddle.github.io/docsify-themeable/) endorsement (currently not compatible with v5 and future is unknown) Miscellaneous updates: - New search plugin options: `insertBefore` and `insertAfter` - Add PostCSS config file - Update BrowserSync config (disable "ghost" mode) - Update tests - Fix Jest + Prettier 3 conflict - Fix `getAndRemoveDocisfyIgnoreConfig` name type (now `Docisfy` => `Docsify`) - Fix execution of sidebar-generating code when `hiddenSidebar` is `true` - Remove `inBrowser` constant (SSR deprecated, so no longer needed)
168 lines
2.6 KiB
Markdown
168 lines
2.6 KiB
Markdown
# Doc helper
|
|
|
|
docsify extends Markdown syntax to make your documents more readable.
|
|
|
|
> Note: For the special code syntax cases, it's better to put them within code backticks to avoid any conflict from configurations or emojis.
|
|
|
|
## Callouts
|
|
|
|
### Important content
|
|
|
|
Important content like:
|
|
|
|
```markdown
|
|
!> **Time** is money, my friend!
|
|
```
|
|
|
|
is rendered as:
|
|
|
|
!> **Time** is money, my friend!
|
|
|
|
### Tips
|
|
|
|
General tips like:
|
|
|
|
```markdown
|
|
?> _TODO_ unit test
|
|
```
|
|
|
|
are rendered as:
|
|
|
|
?> _TODO_ unit test
|
|
|
|
## Link attributes
|
|
|
|
### disabled
|
|
|
|
```md
|
|
[link](/demo ':disabled')
|
|
```
|
|
|
|
### href
|
|
|
|
Sometimes we will use some other relative path for the link, and we have to tell docsify that we don't need to compile this link. For example:
|
|
|
|
```md
|
|
[link](/demo/)
|
|
```
|
|
|
|
It will be compiled to `<a href="/#/demo/">link</a>` and will load `/demo/README.md`. Maybe you want to jump to `/demo/index.html`.
|
|
|
|
Now you can do that
|
|
|
|
```md
|
|
[link](/demo/ ':ignore')
|
|
```
|
|
|
|
You will get `<a href="/demo/">link</a>`html. Do not worry, you can still set the title for the link.
|
|
|
|
```md
|
|
[link](/demo/ ':ignore title')
|
|
|
|
<a href="/demo/" title="title">link</a>
|
|
```
|
|
|
|
### target
|
|
|
|
```md
|
|
[link](/demo ':target=_blank')
|
|
[link](/demo2 ':target=_self')
|
|
```
|
|
|
|
## Task lists
|
|
|
|
```md
|
|
- [ ] foo
|
|
- bar
|
|
- [x] baz
|
|
- [] bam <~ not working
|
|
- [ ] bim
|
|
- [ ] lim
|
|
```
|
|
|
|
- [ ] foo
|
|
- bar
|
|
- [x] baz
|
|
- [] bam <~ not working
|
|
- [ ] bim
|
|
- [ ] lim
|
|
|
|
## Images
|
|
|
|
### Class names
|
|
|
|
```md
|
|
|
|
```
|
|
|
|
### IDs
|
|
|
|
```md
|
|
|
|
```
|
|
|
|
### Sizes
|
|
|
|
```md
|
|
|
|
|
|
|
|
|
|
<!-- Support percentage -->
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
## Heading IDs
|
|
|
|
```md
|
|
### Hello, world! :id=hello-world
|
|
```
|
|
|
|
## Markdown + HTML
|
|
|
|
You need to insert a space between the html and markdown content.
|
|
This is useful for rendering markdown content in the details element.
|
|
|
|
```markdown
|
|
<details>
|
|
<summary>Self-assessment (Click to expand)</summary>
|
|
|
|
- Abc
|
|
- Abc
|
|
|
|
</details>
|
|
```
|
|
|
|
<details>
|
|
<summary>Self-assessment (Click to expand)</summary>
|
|
|
|
- Abc
|
|
- Abc
|
|
|
|
</details>
|
|
|
|
Markdown content can also be wrapped in html tags.
|
|
|
|
```markdown
|
|
<div style='color: red'>
|
|
|
|
- listitem
|
|
- listitem
|
|
- listitem
|
|
|
|
</div>
|
|
```
|
|
|
|
<div style='color: red'>
|
|
|
|
- listitem
|
|
- listitem
|
|
- listitem
|
|
|
|
</div>
|