diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 69 |
1 files changed, 53 insertions, 16 deletions
@@ -24,7 +24,15 @@ The final layout this guide produces, relative to your document root: └── assets/ ├── js/ │ ├── docsify.min.js - │ └── search.min.js + │ ├── search.min.js + │ ├── docsify-copy-code.min.js + │ ├── prism-core.min.js + │ ├── prism-clike.min.js + │ ├── prism-javascript.min.js + │ ├── prism-bash.min.js + │ ├── prism-yaml.min.js + │ ├── prism-python.min.js + │ └── prism-r.min.js └── css/ └── vue.css ``` @@ -70,33 +78,49 @@ Replace `vue.css` in the command above with any of the following if preferred; s * pure.css * vue.css -### Optional: Syntax Highlighting +### Syntax Highlighting (Prism) -If your documentation includes fenced code blocks, download Prism and the language components you need: +Download the Prism highlighting engine and its language components. The core engine +ships **no languages on its own**, so each language is a separate file. Note that +`prism-clike.min.js` is the base grammar that `prism-javascript.min.js` extends, so it +must be downloaded and loaded **before** javascript (see Step 3). ```bash -# Prism core (required) +# Prism core engine (no languages on its own) curl -L "https://cdn.jsdelivr.net/npm/prismjs@1/components/prism-core.min.js" \ -o assets/js/prism-core.min.js -# Language components — add as many as needed +# clike — base grammar required by javascript +curl -L "https://cdn.jsdelivr.net/npm/prismjs@1/components/prism-clike.min.js" \ + -o assets/js/prism-clike.min.js + +# Language components +curl -L "https://cdn.jsdelivr.net/npm/prismjs@1/components/prism-javascript.min.js" \ + -o assets/js/prism-javascript.min.js + curl -L "https://cdn.jsdelivr.net/npm/prismjs@1/components/prism-bash.min.js" \ -o assets/js/prism-bash.min.js curl -L "https://cdn.jsdelivr.net/npm/prismjs@1/components/prism-yaml.min.js" \ -o assets/js/prism-yaml.min.js -curl -L "https://cdn.jsdelivr.net/npm/prismjs@1/components/prism-javascript.min.js" \ - -o assets/js/prism-javascript.min.js +curl -L "https://cdn.jsdelivr.net/npm/prismjs@1/components/prism-python.min.js" \ + -o assets/js/prism-python.min.js + +curl -L "https://cdn.jsdelivr.net/npm/prismjs@1/components/prism-r.min.js" \ + -o assets/js/prism-r.min.js ``` -Then add each `<script>` tag for these files to `index.html` (see Step 3). +To highlight more languages, download additional `prism-<lang>.min.js` files (browse the +[Prism components](https://cdn.jsdelivr.net/npm/prismjs@1/components/)) and add a matching +`<script>` tag in Step 3. Some languages extend others — anything built on `clike` (e.g. +javascript) must load after `prism-clike.min.js`. -### Optional: Copy-to-Clipboard Button +### Copy-to-Clipboard Button -To add a **copy** button to every fenced code block, download the -[docsify-copy-code](https://github.com/jperasmus/docsify-copy-code) plugin. As with -the assets above, it is fetched once and served locally thereafter: +Add a **copy** button to every fenced code block with the +[docsify-copy-code](https://github.com/jperasmus/docsify-copy-code) plugin. Like the +assets above, it is fetched once and served locally thereafter: ```bash # Copy-to-clipboard plugin @@ -148,15 +172,16 @@ Create `index.html`: </script> <script src="assets/js/docsify.min.js"></script> <script src="assets/js/search.min.js"></script> - - <!-- Remove the line below if you did not download the copy-code plugin --> <script src="assets/js/docsify-copy-code.min.js"></script> - <!-- Remove the lines below if you did not download Prism --> + <!-- Prism: core engine first, then clike (required by javascript), then languages --> <script src="assets/js/prism-core.min.js"></script> + <script src="assets/js/prism-clike.min.js"></script> + <script src="assets/js/prism-javascript.min.js"></script> <script src="assets/js/prism-bash.min.js"></script> <script src="assets/js/prism-yaml.min.js"></script> - <script src="assets/js/prism-javascript.min.js"></script> + <script src="assets/js/prism-python.min.js"></script> + <script src="assets/js/prism-r.min.js"></script> </body> </html> ``` @@ -257,7 +282,15 @@ Expected output: ./assets/css ./assets/css/vue.css ./assets/js +./assets/js/docsify-copy-code.min.js ./assets/js/docsify.min.js +./assets/js/prism-bash.min.js +./assets/js/prism-clike.min.js +./assets/js/prism-core.min.js +./assets/js/prism-javascript.min.js +./assets/js/prism-python.min.js +./assets/js/prism-r.min.js +./assets/js/prism-yaml.min.js ./assets/js/search.min.js ./getting-started.md ./index.html @@ -310,5 +343,9 @@ curl -L "https://cdn.jsdelivr.net/npm/docsify@4.13.1/themes/vue.css" \ -o assets/css/vue.css ``` +The Prism components (`prismjs@1`) and the copy-code plugin (`docsify-copy-code@3`) +are versioned independently of Docsify; re-run their Step 2 commands with a pinned +version number the same way when you want to update them. + Check the [Docsify releases page](https://github.com/docsifyjs/docsify/releases) for the latest version number before upgrading. |