diff --git a/docs/api-doc-markdown.md b/docs/api-doc-markdown.md index a37e19d2d4..55ff232821 100644 --- a/docs/api-doc-markdown.md +++ b/docs/api-doc-markdown.md @@ -17,7 +17,7 @@ Documents use the following markdown header fields that are enclosed by a line ` For example: -```markup +``` --- id: doc1 title: My Document @@ -29,7 +29,7 @@ Versioned documents have their ids altered to include the version number when th For example: -```markup +``` --- id: version-1.0.0-doc1 title: My Document @@ -52,7 +52,7 @@ Blog Posts use the following markdown header fields that are enclosed by a line For example: -```markup +``` --- title: My First Blog Post author: Frank Li @@ -91,9 +91,10 @@ Example: You can make an autogenerated list of links, which can be useful as a table of contents for API docs. -In your markdown file, insert a line with the text <`AUTOGENERATED_TABLE_OF_CONTENTS>`. Write your documentation using `h3` headers for each function inside a code block. These will be found by Docusaurus and a list of links to these sections will inserted at the text <`AUTOGENERATED_TABLE_OF_CONTENTS>`. +In your markdown file, insert a line with the text <`AUTOGENERATED_TABLE_OF_CONTENTS`>. Write your documentation using `h3` headers for each function inside a code block. These will be found by Docusaurus and a list of links to these sections will inserted at the text <`AUTOGENERATED_TABLE_OF_CONTENTS`>. Example: + ```markdown ### `docusaurus.function(a, b)` @@ -111,4 +112,50 @@ will lead to a table of contents of the functions: - `docusaurus.function(a, b)` - `docdoc(file)` ``` + and each function will link to their corresponding sections in the page. + +## Syntax Highlighting + +Syntax highlighting is enabled by default on fenced code blocks. The language should be detected automatically, but you can sometimes get better results by specifying the language. You can do so using an [info string](https://github.github.com/gfm/#example-111), following the three opening backticks. The following JavaScript example... + + ```javascript + ReactDOM.render( +

Hello, world!

, + document.getElementById('root') + ); + ``` + +...would be rendered with syntax highlighting like so: + +```javascript +ReactDOM.render( +

Hello, world!

, + document.getElementById('root') +); +``` + +Highlighting is provided by [Highlight.js](https://highlightjs.org) using the theme specified in your `siteConfig.js` file as part of the `highlight` key: + +``` +highlight: { + theme: 'default' +} +``` + +You can find the full list of supported themes in the Highlight.js [`styles`](https://github.com/isagalaev/highlight.js/tree/master/src/styles) directory. + +### Registering additional languages + +While Highlight.js provides support for [many popular languages out of the box](https://highlightjs.org/static/demo/), you may find the need to register additional language support. For these cases, we provide an escape valve by exposing the `hljs` constant as part of the `highlight` config key. This in turn allows you to call [`registerLanguage`](http://highlightjs.readthedocs.io/en/latest/api.html#registerlanguage-name-language): + +``` +highlight: { + theme: 'default', + hljs: function(hljs) { + hljs.registerLanguage('galacticbasic', function(hljs) { + // ... + }); + } +} +``` diff --git a/docs/api-pages.md b/docs/api-pages.md index 19678df974..9f9b26332d 100644 --- a/docs/api-pages.md +++ b/docs/api-pages.md @@ -127,7 +127,7 @@ Static assets should be placed into the `website/static` folder. They can be acc ## Styles -You should configure your site's primary, secondary, and Prism colors using the `colors` field in `siteConfig` as specified [here](site-config.md). You can also configure other colors in the same way as described in the `siteConfig` doc. +You should configure your site's primary, secondary, and code block colors using the `colors` field in `siteConfig` as specified [here](api-site-config.md). You can also configure other colors in the same way as described in the `siteConfig` doc. You can provide your own custom styles by adding them anywhere in the `website/static` folder. Any `.css` files you provide in the `static` folder will get concatenated to the end of Docusaurus's provided styles, allowing you to add to or override Docusaurus default styles as you wish. diff --git a/docs/api-site-config.md b/docs/api-site-config.md index deac13c5d3..5641fb81d3 100644 --- a/docs/api-site-config.md +++ b/docs/api-site-config.md @@ -56,7 +56,6 @@ headerLinks: [ - `primaryColor` is the color used the header navigation bar and sidebars. - `secondaryColor` is the color seen in the second row of the header navigation bar when the site window is narrow (including on mobile). - - `prismColor` is the color used in the background of syntax highlighting for code in documentation. It is recommended to be the same color as `primaryColor` in `rgba` form with an alpha value of `0.03`. Other fields can be added - Custom color configurations can also be added. For example, if user styles are added with colors specified as `$myColor`, then adding a `myColor` field to `colors` will allow you to easily configure this color. `copyright` - The copyright string at footer of site and within feed @@ -81,9 +80,18 @@ headerLinks: [ `gaTrackingId` - Google Analytics tracking ID to track page views. - `sourceCodeButton` - the type of button to use for pointing to your source code. If this field is non-null, the site will pull in the appropriate button code in the header, for you to be able to render as you see fit. Currently accepted values: `"github"`, `"none"`. Defaults to `"github"`. +`highlight` - [Syntax highlighting](api-doc-markdown.md) options: + + - `theme` is the name of the theme used by Highlight.js when highlighting code. + - `version` specifies a particular version of Highlight.js to be used. + - `hljs` provides an escape valve by passing an instance of Highlight.js to the function specified here, allowing additional languages to be registered for syntax highlighting. + +`markdownPlugins` - An array of plugins to be loaded by Remarkable, the markdown parser and renderer used by Docusaurus. The plugin will receive a reference to the Remarkable instance, allowing custom parsing and rendering rules to be defined. + +`scripts` - Array of JavaScript sources to load. The script tag will be inserted in the HTML head. + Users can also add their own custom fields if they wish to provide some data across different files. ## Example siteConfig.js with all fields @@ -118,12 +126,8 @@ const siteConfig = { favicon: "img/favicon.png", colors: { primaryColor: "#2E8555", - secondaryColor: "#205C3B", - prismColor: - "rgba(46, 133, 85, 0.03)" + secondaryColor: "#205C3B" }, - - editUrl: "https://github.com/deltice/test-site/edit/master/docs/", users, disableHeaderTitle: true, @@ -138,9 +142,20 @@ const siteConfig = { indexName: "github" }, gaTrackingId: "U-A2352", - sourceCodeButton: "github" + sourceCodeButton: "github", + highlight: { + theme: 'default' + }, + markdownPlugins: [ + function foo(md) { + md.renderer.rules.fence_custom.foo = function(tokens, idx, options, env, instance) { + return '
bar
'; + } + } + ], + scripts: [ "https://docusaurus.io/slash.js" ] + }; module.exports = siteConfig; - ``` diff --git a/examples/basics/siteConfig.js b/examples/basics/siteConfig.js index 72cd71f2f8..b0111fda30 100644 --- a/examples/basics/siteConfig.js +++ b/examples/basics/siteConfig.js @@ -35,15 +35,17 @@ const siteConfig = { /* colors for website */ colors: { primaryColor: "#2E8555", - secondaryColor: "#205C3B", - prismColor: - "rgba(46, 133, 85, 0.03)" /* primaryColor in rgba form, with 0.03 alpha */ + secondaryColor: "#205C3B" }, // This copyright info is used in /core/Footer.js and blog rss/atom feeds. copyright: "Copyright © " + new Date().getFullYear() + - " Your Name or Your Company Name" + " Your Name or Your Company Name", + highlight: { + // Highlight.js theme to use for syntax highlighting in code blocks + theme: "default" + } }; module.exports = siteConfig; diff --git a/lib/core/CompLibrary.js b/lib/core/CompLibrary.js index 8d7fa9dcc9..d49152b01c 100644 --- a/lib/core/CompLibrary.js +++ b/lib/core/CompLibrary.js @@ -8,12 +8,10 @@ const Marked = require("./Marked.js"); const Container = require("./Container.js"); const GridBlock = require("./GridBlock.js"); -const Prism = require("./Prism.js"); // collection of other components to provide to users module.exports = { Marked: Marked, Container: Container, - GridBlock: GridBlock, - Prism: Prism + GridBlock: GridBlock }; diff --git a/lib/core/Head.js b/lib/core/Head.js index 16251f3795..c912faacb0 100644 --- a/lib/core/Head.js +++ b/lib/core/Head.js @@ -10,15 +10,24 @@ const React = require("react"); // html head for each page class Head extends React.Component { render() { - let links = this.props.config.headerLinks; + const links = this.props.config.headerLinks; let hasBlog = false; links.map(link => { if (link.blog) hasBlog = true; }); - let sourceCodeButton = this.props.config.sourceCodeButton; - // defaults to github, but other values may be allowed in the future - let includeGithubButton = + const sourceCodeButton = this.props.config.sourceCodeButton; + // defaults to GitHub, but other values may be allowed in the future + const includeGitHubButton = sourceCodeButton === "github" || sourceCodeButton == null; + + const highlightDefaultVersion = '9.12.0'; + const highlightConfig = this.props.config.highlight + || { version: highlightDefaultVersion, theme: 'default' }; + const highlightVersion = highlightConfig.version || highlightDefaultVersion; + const highlightTheme = highlightConfig.theme || 'default'; + + const hasCustomScripts = this.props.config.scripts; + return ( @@ -64,7 +73,7 @@ class Head extends React.Component { href={this.props.config.url + "/blog/atom.xml"} title={this.props.config.title + " Blog ATOM Feed"} /> - )}{" "} + )} {hasBlog && ( )} - {includeGithubButton && ( + {includeGitHubButton && ( +