Skip to content

Commit

Permalink
Update docs and migrate to new syntax
Browse files Browse the repository at this point in the history
  • Loading branch information
jhildenbiddle authored and sy-records committed Aug 11, 2024
1 parent f9950e0 commit f9a9869
Show file tree
Hide file tree
Showing 15 changed files with 65 additions and 50 deletions.
4 changes: 2 additions & 2 deletions docs/adding-pages.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,7 @@ To create section headers:

You need to create a `.nojekyll` in `./docs` to prevent GitHub Pages from ignoring files that begin with an underscore.

!> Docsify only looks for `_sidebar.md` in the current folder, and uses that, otherwise it falls back to the one configured using `window.$docsify.loadSidebar` config.
> [!IMPORTANT] Docsify only looks for `_sidebar.md` in the current folder, and uses that, otherwise it falls back to the one configured using `window.$docsify.loadSidebar` config.
Example file structure:

Expand Down Expand Up @@ -98,7 +98,7 @@ You can specify `alias` to avoid unnecessary fallback.
</script>
```

!> You can create a `README.md` file in a subdirectory to use it as the landing page for the route.
> [!IMPORTANT] You can create a `README.md` file in a subdirectory to use it as the landing page for the route.
## Set Page Titles from Sidebar Selection

Expand Down
4 changes: 2 additions & 2 deletions docs/cdn.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ Uncompressed resources are available by omitting the `.min` from the filename.

Specifying the latest major version allows your site to receive all non-breaking enhancements ("minor" updates) and bug fixes ("patch" updates) as they are released. This is good option for those who prefer a zero-maintenance way of keeping their site up to date with minimal risk as new versions are published.

?> When a new major version is released, you will need to manually update the major version number after the `@` symbol in your CDN URLs.
> [!TIP] When a new major version is released, you will need to manually update the major version number after the `@` symbol in your CDN URLs.
<!-- prettier-ignore -->
```html
Expand All @@ -44,7 +44,7 @@ Specifying the latest major version allows your site to receive all non-breaking

Specifying an exact version prevents any future updates from affecting your site. This is good option for those who prefer to manually update their resources as new versions are published.

?> When a new version is released, you will need to manually update the version number after the `@` symbol in your CDN URLs.
> [!TIP] When a new version is released, you will need to manually update the version number after the `@` symbol in your CDN URLs.
<!-- prettier-ignore -->
```html
Expand Down
8 changes: 4 additions & 4 deletions docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -301,7 +301,7 @@ Key `bindings` are defined as case insensitive string values separated by `+`. M

The `callback` function receive a [keydown event](https://developer.mozilla.org/en-US/docs/Web/API/Element/keydown_event) as an argument.

!> Let site visitors know your custom key bindings are available! If a binding is associated with a DOM element, consider inserting a `<kbd>` element as a visual cue (e.g., <kbd>alt</kbd> + <kbd>a</kbd>) or adding [title](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title) and [aria-keyshortcuts](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-keyshortcuts) attributes for hover/focus hints.
> [!IMPORTANT] Let site visitors know your custom key bindings are available! If a binding is associated with a DOM element, consider inserting a `<kbd>` element as a visual cue (e.g., <kbd>alt</kbd> + <kbd>a</kbd>) or adding [title](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title) and [aria-keyshortcuts](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-keyshortcuts) attributes for hover/focus hints.
```js
window.$docsify = {
Expand Down Expand Up @@ -376,7 +376,7 @@ window.$docsify = {

Website logo as it appears in the sidebar. You can resize it using CSS.

!> Logo will only be visible if `name` prop is also set. See [name](#name) configuration.
> [!IMPORTANT] Logo will only be visible if `name` prop is also set. See [name](#name) configuration.
```js
window.$docsify = {
Expand Down Expand Up @@ -919,7 +919,7 @@ For more details, see [#1131](https://github.com/docsifyjs/docsify/issues/1131).

## themeColor ⚠️

!> Deprecated as of v5. Use the `--theme-color` [theme property](themes#theme-properties) to [customize](themes#customization) your theme color.
> [!IMPORTANT] Deprecated as of v5. Use the `--theme-color` [theme property](themes#theme-properties) to [customize](themes#customization) your theme color.
- Type: `String`

Expand All @@ -933,7 +933,7 @@ window.$docsify = {

## topMargin ⚠️

!> Deprecated as of v5. Use the `--scroll-padding-top` [theme property](themes#theme-properties) to specify a scroll margin when using a sticky navbar.
> [!IMPORTANT] Deprecated as of v5. Use the `--scroll-padding-top` [theme property](themes#theme-properties) to specify a scroll margin when using a sticky navbar.
- Type: `Number|String`
- Default: `0`
Expand Down
4 changes: 2 additions & 2 deletions docs/custom-navbar.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

If you need custom navigation, you can create a HTML-based navigation bar.

!> Note that documentation links begin with `#/`.
> [!IMPORTANT] Note that documentation links begin with `#/`.
```html
<!-- index.html -->
Expand Down Expand Up @@ -51,7 +51,7 @@ To create drop-down menus:
- [chinese](/zh-cn/)
```

!> You need to create a `.nojekyll` in `./docs` to prevent GitHub Pages from ignoring files that begin with an underscore.
> [!IMPORTANT] You need to create a `.nojekyll` in `./docs` to prevent GitHub Pages from ignoring files that begin with an underscore.
`_navbar.md` is loaded from each level directory. If the current directory doesn't have `_navbar.md`, it will fall back to the parent directory. If, for example, the current path is `/guide/quick-start`, the `_navbar.md` will be loaded from `/guide/_navbar.md`.

Expand Down
10 changes: 5 additions & 5 deletions docs/deploy.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,14 +14,14 @@ It is recommended that you save your files to the `./docs` subfolder of the `mai

![GitHub Pages](_images/deploy-github-pages.png)

!> You can also save files in the root directory and select `main branch`.
You'll need to place a `.nojekyll` file in the deploy location (such as `/docs` or the gh-pages branch)
> [!IMPORTANT] You can also save files in the root directory and select `main branch`.
> You'll need to place a `.nojekyll` file in the deploy location (such as `/docs` or the gh-pages branch)
## GitLab Pages

If you are deploying your master branch, create a `.gitlab-ci.yml` with the following script:

?> The `.public` workaround is so `cp` doesn't also copy `public/` to itself in an infinite loop.
> [!TIP] The `.public` workaround is so `cp` doesn't also copy `public/` to itself in an infinite loop.
```YAML
pages:
Expand All @@ -37,11 +37,11 @@ pages:
- master
```
!> You can replace script with `- cp -r docs/. public`, if `./docs` is your Docsify subfolder.
> [!IMPORTANT] You can replace script with `- cp -r docs/. public`, if `./docs` is your Docsify subfolder.

## Firebase Hosting

!> You'll need to install the Firebase CLI using `npm i -g firebase-tools` after signing into the [Firebase Console](https://console.firebase.google.com) using a Google Account.
> [!IMPORTANT] You'll need to install the Firebase CLI using `npm i -g firebase-tools` after signing into the [Firebase Console](https://console.firebase.google.com) using a Google Account.

Using a terminal, determine and navigate to the directory for your Firebase Project. This could be `~/Projects/Docs`, etc. From there, run `firebase init` and choose `Hosting` from the menu (use **space** to select, **arrow keys** to change options and **enter** to confirm). Follow the setup instructions.

Expand Down
8 changes: 4 additions & 4 deletions docs/embed-files.md
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,7 @@ Example:

If you embed the file as `iframe`, `audio` and `video`, then you may need to set the attributes of these tags.

?> Note, for the `audio` and `video` types, docsify adds the `controls` attribute by default. When you want add more attributes, the `controls` attribute need to be added manually if need be.
> [!TIP] Note, for the `audio` and `video` types, docsify adds the `controls` attribute by default. When you want add more attributes, the `controls` attribute need to be added manually if need be.
```md
[filename](_media/example.mp4 ':include :type=video controls width=100%')
Expand All @@ -101,13 +101,13 @@ Embedding any type of source code file, you can specify the highlighted language

[](_media/example.html ':include :type=code text')

?> How to set highlight? You can see [here](language-highlight.md).
> [!TIP] How to set highlight? You can see [here](language-highlight.md).
## Embed a gist

You can embed a gist as markdown content or as a code block - this is based on the approach at the start of [Embed Files](#embed-files) section, but uses a raw gist URL as the target.

?> **No** plugin or app config change is needed here to make this work. In fact, the "Embed" `script` tag that is copied from a gist will _not_ load even if you make plugin or config changes to allow an external script.
> [!TIP] **No** plugin or app config change is needed here to make this work. In fact, the "Embed" `script` tag that is copied from a gist will _not_ load even if you make plugin or config changes to allow an external script.
### Identify the gist's metadata

Expand All @@ -132,7 +132,7 @@ Here are two examples based on the sample gist:
- https://gist.githubusercontent.com/anikethsaha/f88893bb563bb7229d6e575db53a8c15/raw/content.md
- https://gist.githubusercontent.com/anikethsaha/f88893bb563bb7229d6e575db53a8c15/raw/script.js

?> Alternatively, you can get a raw URL directly clicking the _Raw_ button on a gist file. But, if you use that approach, just be sure to **remove** the revision number between `raw/` and the filename so that the URL matches the pattern above instead. Otherwise your embedded gist will **not** show the latest content when the gist is updated.
> [!TIP] Alternatively, you can get a raw URL directly clicking the _Raw_ button on a gist file. But, if you use that approach, just be sure to **remove** the revision number between `raw/` and the filename so that the URL matches the pattern above instead. Otherwise your embedded gist will **not** show the latest content when the gist is updated.
Continue with one of the sections below to embed the gist on a Docsify page.

Expand Down
8 changes: 4 additions & 4 deletions docs/helpers.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,16 +52,16 @@ Docsify supports [GitHub style](https://docs.github.com/en/get-started/writing-o

The following Docsify v4 callout syntax has been deprecated and will be removed in a future version.

!> **Important** callouts communicate information necessary for users to succeed.
!> Legacy **Important** callouts are deprecated.

?> **Tip** callouts communicate optional information to help a user be more successful.
?> Legacy **Tip** callouts are deprecated.

**Markdown**

```markdown
!> **Important** callouts communicate information necessary for users to succeed.
!> Legacy **Important** callouts are deprecated.

?> **Tip** callouts communicate optional information to help a user be more successful.
?> Legacy **Tip** callouts are deprecated.
```

## Link attributes
Expand Down
6 changes: 6 additions & 0 deletions docs/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,12 @@
disabled
/>

<!-- Prism Theme -->
<!-- <link
rel="stylesheet"
href="//cdn.jsdelivr.net/npm/[email protected]/themes/prism-twilight.min.css"
/> -->

<!-- Site styles -->
<style>
/* Plugin: Carbon Ads */
Expand Down
4 changes: 2 additions & 2 deletions docs/language-highlight.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ function add(a, b) {

Support for additional [languages](https://prismjs.com/#supported-languages) is available by loading the Prism [grammar files](https://cdn.jsdelivr.net/npm/prismjs@1/components/):

!> Prism grammar files must be loaded after Docsify.
> [!IMPORTANT] Prism grammar files must be loaded after Docsify.
```html
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-bash.min.js"></script>
Expand All @@ -79,7 +79,7 @@ Support for additional [languages](https://prismjs.com/#supported-languages) is

Docsify's official [themes](themes) are compatible with Prism syntax highlighting themes.

!> Prism themes must be loaded after Docsify themes.
> [!IMPORTANT] Prism themes must be loaded after Docsify themes.
```html
<!-- Light and dark mode -->
Expand Down
2 changes: 1 addition & 1 deletion docs/markdown.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ window.$docsify = {
};
```

?> Configuration Options Reference: [marked documentation](https://marked.js.org/#/USING_ADVANCED.md)
> [!TIP] Configuration Options Reference: [marked documentation](https://marked.js.org/#/USING_ADVANCED.md)
You can completely customize the parsing rules.

Expand Down
2 changes: 1 addition & 1 deletion docs/plugins.md
Original file line number Diff line number Diff line change
Expand Up @@ -123,7 +123,7 @@ Install the plugin and configure the track id.

Renders a larger collection of emoji shorthand codes. Without this plugin, Docsify is able to render only a limited number of emoji shorthand codes.

!> Deprecated as of v4.13. Docsify no longer requires this plugin for full emoji support.
> [!IMPORTANT] Deprecated as of v4.13. Docsify no longer requires this plugin for full emoji support.
```html
<script src="//cdn.jsdelivr.net/npm/docsify@5/dist/plugins/emoji.min.js"></script>
Expand Down
4 changes: 2 additions & 2 deletions docs/quickstart.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ Run the local server with `docsify serve`. You can preview your site in your bro
docsify serve docs
```

?> For more use cases of `docsify-cli`, head over to the [docsify-cli documentation](https://github.com/docsifyjs/docsify-cli).
> [!TIP] For more use cases of `docsify-cli`, head over to the [docsify-cli documentation](https://github.com/docsifyjs/docsify-cli).
## Manual initialization

Expand Down Expand Up @@ -76,7 +76,7 @@ Download or create an `index.html` template using the following markup:

### Specifying docsify versions

?> Note that in both of the examples below, docsify URLs will need to be manually updated when a new major version of docsify is released (e.g. `v5.x.x` => `v6.x.x`). Check the docsify website periodically to see if a new major version has been released.
> [!TIP] Note that in both of the examples below, docsify URLs will need to be manually updated when a new major version of docsify is released (e.g. `v5.x.x` => `v6.x.x`). Check the docsify website periodically to see if a new major version has been released.
Specifying a major version in the URL (`@5`) will allow your site to receive non-breaking enhancements (i.e. "minor" updates) and bug fixes (i.e. "patch" updates) automatically. This is the recommended way to load docsify resources.

Expand Down
6 changes: 3 additions & 3 deletions docs/themes.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ The Docsify "core" theme contains all of the styles and [theme properties](#them

Theme add-ons are used in combination with the [core theme](#core-theme). Add-ons contain CSS rules that modify [theme properties](#theme-properties) values and/or add custom style declarations. They can often (but not always) be used with other add-ons.

!> Theme add-ons must be loaded after the [core theme](#core-theme).
> [!IMPORTANT] Theme add-ons must be loaded after the [core theme](#core-theme).
<!-- prettier-ignore -->
```html
Expand Down Expand Up @@ -288,7 +288,7 @@ Docsify provides [theme properties](#theme-properties) for simplified customizat
}
```

?> **Theme authors**: Consider providing instructions for loading your recommended web fonts manually instead of including them in your theme using `@import`. This allows users who prefer a different font to avoid loading your recommended web font(s) unnecessarily.
> [!TIP] **Theme authors**: Consider providing instructions for loading your recommended web fonts manually instead of including them in your theme using `@import`. This allows users who prefer a different font to avoid loading your recommended web font(s) unnecessarily.
4. Advanced styling may require custom CSS declarations. This is expected, however custom CSS declarations may break when new versions of Docsify are released. When possible, leverage [theme properties](#theme-properties) instead of custom declarations or lock your [CDN](cdn) URLs to a [specific version](cdn#specific-version) to avoid potential issues when using custom CSS declarations.

Expand All @@ -302,7 +302,7 @@ Docsify provides [theme properties](#theme-properties) for simplified customizat

The following properties are available in all official Docsify themes. Default values for the "Core" theme are shown.

?> **Theme and plugin authors**: We encourage you to leverage these custom theme properties and to offer similar customization options in your projects.
> [!TIP] **Theme and plugin authors**: We encourage you to leverage these custom theme properties and to offer similar customization options in your projects.
### Common

Expand Down
43 changes: 26 additions & 17 deletions docs/ui-kit.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,45 +53,54 @@

## Callouts

### Github Style

<!-- prettier-ignore -->
> [!CAUTION]
> **Caution** callouts communicate negative potential consequences of an action.
> **Caution** callout with `inline code`.
<!-- prettier-ignore -->
> [!IMPORTANT]
> **Important** callouts communicate information necessary for users to succeed.
> **Important** callout with `inline code`.
<!-- prettier-ignore -->
> [!NOTE]
> **Note** callouts communicate information that users should take into account.
> **Note** callout with `inline code`.
<!-- prettier-ignore -->
> [!TIP]
> **Tip** callouts communicate optional information to help a user be more successful.
> **Tip** callout with `inline code`.
<!-- prettier-ignore -->
> [!WARNING]
> **Warning** callouts communicate potential risks user should be aware of.
> **Warning** callout with `inline code`.
**Multi Line**

<!-- prettier-ignore -->
> [!NOTE]
> - List item 1
> - List item 2
>
> Text
>
> ```html
> <p>Hello, World!</p>
> ```
**Nested**
<!-- prettier-ignore -->
> [!CAUTION]
> **Caution** callouts communicate negative potential consequences of an action.
> > [!IMPORTANT]
> > **Important** callouts communicate information necessary for users to succeed.
> [!NOTE]
> Level 1
> > [!NOTE]
> > Level 2
> > > [!NOTE]
> > > **Note** callouts communicate information that users should take into account.
> > > Level 3
#### Legacy Docsify Style
**Legacy Style**
!> **Important** callout with `inline code` and additional placeholder text used
to force the content to wrap and span multiple lines.
!> Legacy **Important** callout with `inline code`.
?> **Tip** callout with `inline code` and additional placeholder text used to
force the content to wrap and span multiple lines.
?> Legacy **Tip** with `inline code`.
## Code
Expand Down
2 changes: 1 addition & 1 deletion docs/vue.md
Original file line number Diff line number Diff line change
Expand Up @@ -311,7 +311,7 @@ window.$docsify = {

Vue content can mounted using a `<script>` tag in your markdown pages.

!> Only the first `<script>` tag in a markdown file is executed. If you wish to mount multiple Vue instances using a script tag, all instances must be mounted within the first script tag in your markdown.
> [!IMPORTANT] Only the first `<script>` tag in a markdown file is executed. If you wish to mount multiple Vue instances using a script tag, all instances must be mounted within the first script tag in your markdown.
```html
<script>
Expand Down

0 comments on commit f9a9869

Please sign in to comment.