Skip to content

Commit 87813b1

Browse files
andrewbranchandrewbranch
committed
Add docs
1 parent 9407dac commit 87813b1

File tree

1 file changed

+131
-15
lines changed

1 file changed

+131
-15
lines changed

‎README.md

Lines changed: 131 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -24,9 +24,11 @@ If you’re updating from v1.x.x to v2.x.x, see [MIGRATING.md](./MIGRATING.md).
2424
- [Variables](#variables)
2525
- [Tweaking or replacing theme colors](#tweaking-or-replacing-theme-colors)
2626
- [Extra stuff](#extra-stuff)
27+
- [Inline code highlighting](#inline-code-highlighting)
2728
- [Line highlighting](#line-highlighting)
2829
- [Using different themes for different code fences](#using-different-themes-for-different-code-fences)
2930
- [Arbitrary code fence options](#arbitrary-code-fence-options)
31+
- [Options reference](#options-reference)
3032
- [Contributing](#contributing)
3133

3234
## Why gatsby-remark-vscode?
@@ -48,7 +50,7 @@ Install the package:
4850
npm install --save gatsby-remark-vscode
4951
```
5052

51-
Add to your `gatsby-config.js` (all options are optional; defaults shown here):
53+
Add to your `gatsby-config.js`:
5254

5355
```js
5456
{
@@ -58,21 +60,8 @@ Add to your `gatsby-config.js` (all options are optional; defaults shown here):
5860
options: {
5961
plugins: [{
6062
resolve: `gatsby-remark-vscode`,
61-
// All options are optional. Defaults shown here.
6263
options: {
63-
theme: 'Dark+ (default dark)', // Read on for list of included themes. Also accepts object and function forms.
64-
wrapperClassName: '', // Additional class put on 'pre' tag. Also accepts function to set the class dynamically.
65-
injectStyles: true, // Injects (minimal) additional CSS for layout and scrolling
66-
extensions: [], // Third-party extensions providing additional themes and languages
67-
languageAliases: {}, // Map of custom/unknown language codes to standard/known language codes
68-
replaceColor: x => x, // Function allowing replacement of a theme color with another. Useful for replacing hex colors with CSS variables.
69-
getLineClassName: ({ // Function allowing dynamic setting of additional class names on individual lines
70-
content, // - the string content of the line
71-
index, // - the zero-based index of the line within the code fence
72-
language, // - the language specified for the code fence
73-
meta // - any options set on the code fence alongside the language (more on this later)
74-
}) => '',
75-
logLevel: 'warn' // Set to 'info' to debug if something looks wrong
64+
theme: 'Abyss' // Or install your favorite theme from GitHub
7665
}
7766
}]
7867
}
@@ -329,6 +318,41 @@ Since the CSS for token colors is auto-generated, it’s fragile and inconvenien
329318

330319
## Extra stuff
331320

321+
### Inline code highlighting
322+
323+
To highlight inline code spans, add an `inlineCode` key to the plugin options and choose a `marker` string:
324+
325+
```js
326+
{
327+
inlineCode: {
328+
marker: '•'
329+
}
330+
}
331+
```
332+
333+
Then, in your Markdown, you can prefix code spans by the language name followed by the `marker` string to opt into highlighting that span:
334+
335+
```md
336+
Now you can highlight inline code: `js•Array.prototype.concat.apply([], array)`.
337+
```
338+
339+
The syntax theme defaults to the one selected for code blocks, but you can control the inline code theme independently:
340+
341+
```js
342+
{
343+
theme: 'Default Dark+',
344+
inlineCode: {
345+
marker: '•',
346+
theme: {
347+
default: 'Default Light+',
348+
dark: 'Default Dark+'
349+
}
350+
}
351+
}
352+
```
353+
354+
See [`inlineCode`](#inlinecode) in the options reference for more API details.
355+
332356
### Line highlighting
333357

334358
`gatsby-remark-vscode` offers the same line-range-after-language-name strategy of highlighting or emphasizing lines as [gatsby-remark-prismjs](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-remark-prismjs):
@@ -416,6 +440,98 @@ Line numbers and ranges aren’t the only things you can pass as options on your
416440
}
417441
```
418442

443+
## Options reference
444+
445+
### `theme`
446+
447+
The syntax theme used for code blocks.
448+
449+
- **Default:** `'Default Dark+'`
450+
- **Accepted types**:
451+
- **`string`:** The name or id of a theme. (See [Built-in themes](#themes) and [Using languages and themes from an extension](#using-languages-and-themes-from-an-extension).)
452+
- **`ThemeSettings`:** An object that selects different themes to use in different contexts. (See [Multi-theme support](#multi-theme-support).)
453+
- **`(data: CodeBlockData) => string | ThemeSettings`:** A function returning the theme selection for a given code block. `CodeBlockData` is an object with properties:
454+
- **`language`:** The language of the code block, if one was specified.
455+
- **`markdownNode`:** The MarkdownRemark GraphQL node.
456+
- **`node`:** The Remark AST node of the code block.
457+
- **`parsedOptions`:** The object form of of any code fence info supplied. (See [Arbitrary code fence options](#arbitrary-code-fence-options).)
458+
459+
### `wrapperClassName`
460+
461+
A custom class name to be set on the `pre` tag.
462+
463+
- **Default:** None, but the class `grvsc-container` will always be on the tag.
464+
- **Accepted types:**
465+
- **`string`:** The class name to add.
466+
- **`(data: CodeBlockData) => string`:** A function returning the class name to add for a given code block. (See the [`theme`](#theme) option above for the details of `CodeBlockData`.)
467+
468+
### `languageAliases`
469+
470+
An object that allows additional language names to be mapped to recognized languages so they can be used on opening code fences:
471+
472+
```js
473+
{
474+
languageAliases: {
475+
fish: 'sh'
476+
}
477+
}
478+
```
479+
480+
````md
481+
Then you can use code fences like this:
482+
483+
```fish
484+
ls -la
485+
```
486+
487+
And they’ll be parsed as shell script (`sh`).
488+
````
489+
490+
- **Default:** None, but many built-in languages are already recognized by a variety of names.
491+
- **Accepted type:** `Record<string, string>`; that is, an object with string keys and string values.
492+
493+
### `extensions`
494+
495+
A list of third party extensions to search for additional langauges and themes. (See [Using languages and themes from an extension](#using-languages-and-themes-from-an-extension).)
496+
497+
- **Default:** None
498+
- **Accepted type:** `string[]`; that is, an array of strings, where the strings are the package names of the extensions.
499+
500+
### `inlineCode`
501+
502+
Enables syntax highlighting for inline code spans. (See [Inline code highlighting](#inline-code-highlighting).)
503+
504+
- **Default:** None
505+
- **Accepted type:** An object with properties:
506+
- **`theme`:** A string or `ThemeSettings` object selecting the theme, or a function returning a string or `ThemeSettings` object for a given code span. The type is the same as the one documented in the top-level [theme option](#theme). Defaults to the value of the top-level [theme option](#theme).
507+
- **`marker`:** A string used as a separator between the language name and the content of a code span. For example, with a `marker` of value `'•'`, you can highlight a code span as JavaScript by writing the Markdown code span as `` `js•Code.to.highlight("inline")` ``.
508+
- **`className`:** A string, or function returning a string for a given code span, that sets a custom class name on the wrapper `code` HTML tag. If the function form is used, it is passed an object parameter describing the code span with properties:
509+
- **`language`:** The language of the code span (the bit before the `marker` character).
510+
- **`markdownNode`:** The MarkdownRemark GraphQL node.
511+
- **`node`:** The Remark AST node of the code span.
512+
513+
### `injectStyles`
514+
515+
Whether to add supporting CSS to the end of the Markdown document. (See [Styles](#styles).)
516+
517+
- **Default:** `true`
518+
- **Accepted type:** `boolean`
519+
520+
### `replaceColor`
521+
522+
A function allowing individual color values to be replaced in the generated CSS. (See [Tweaking or replacing theme colors](#tweaking-or-replacing-theme-colors).)
523+
524+
- **Default:** None
525+
- **Accepted type:** `(colorValue: string, theme: string) => string`; that is, a function that takes the original color and the identifier of the theme it came from and returns a new color value.
526+
527+
### `logLevel`
528+
529+
The verbosity of logging. Useful for diagnosing unexpected behavior.
530+
531+
- **Default**: `'warn'`
532+
- **Accepted values:** From most verbose to least verbose, `'trace'`, `'debug'`, `'info'`, `'warn'`, or `'error'`.
533+
534+
419535
## Contributing
420536

421537
Please note that this project is released with a Contributor [Code of Conduct](./CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms.

0 commit comments

Comments
 (0)