1 | # slate-edit-code
|
2 |
|
3 | [![NPM version](https://badge.fury.io/js/slate-edit-code.svg)](http://badge.fury.io/js/slate-edit-code)
|
4 | [![Linux Build Status](https://travis-ci.org/GitbookIO/slate-edit-code.png?branch=master)](https://travis-ci.org/GitbookIO/slate-edit-code)
|
5 |
|
6 | A Slate plugin to handle code block editing.
|
7 |
|
8 | ### Install
|
9 |
|
10 | ```js
|
11 | npm install slate-edit-code
|
12 | ```
|
13 |
|
14 | ### Features
|
15 |
|
16 | - Pressing <kbd>Enter</kbd> insert a new line starting with the right indentation
|
17 | - Pressing <kbd>Tab</kbd> insert the right indentation if selection is collapsed or indent all lines in selection
|
18 | - Pressing <kbd>Delete</kbd> remove the indentation before cursor if possible
|
19 | - Pressing <kbd>Mod+Enter</kbd> exits the code block
|
20 | - Pressing <kbd>Mod+A</kbd> selects all the text in the block
|
21 |
|
22 | > <kbd>Mod</kbd> means <kbd>Ctrl</kbd> on Windows/Linux and <kbd>Command</kbd> on Mac.
|
23 |
|
24 | ### Structure
|
25 |
|
26 | This plugin uses the following structure for code blocks:
|
27 |
|
28 | ``` yaml
|
29 | nodes:
|
30 | - object: block
|
31 | type: code_block
|
32 | nodes:
|
33 | - object: block
|
34 | type: code_line
|
35 | nodes:
|
36 | - text: "A code block is made of..."
|
37 | - object: block
|
38 | type: code_line
|
39 | nodes:
|
40 | - text: "...several code lines"
|
41 |
|
42 | ```
|
43 |
|
44 | The plugin automatically converts multiline texts in `code_blocks` into the appropriate number of `code_lines`.
|
45 |
|
46 |
|
47 | ### Simple Usage
|
48 |
|
49 | ```js
|
50 | import EditCode from 'slate-edit-code'
|
51 |
|
52 | const plugins = [
|
53 | EditCode()
|
54 | ]
|
55 | ```
|
56 |
|
57 | #### Options arguments
|
58 |
|
59 | - `containerType = 'code_block' : string` — The type of the code containers
|
60 | - `lineType = 'code_line' : string` — The type of the code lines
|
61 | - `exitBlockType = 'paragraph' : null | string` — <kbd>Mod+Enter</kbd> will exit the code container, into the given block type. Backspace at start of an empty code container will convert it to the given block type. Pass `null` to disable this behavior.
|
62 | - `onExit: (Change) => void | Change` — Change to do when the user hits <kbd>Mod+Enter</kbd>. Defaults to exiting the code block, into a new `exitBlockType` block.
|
63 | - `selectAll = true : boolean` — True to select all code inside a code container on <kbd>Mod+A</kbd>
|
64 | - `allowMarks = false : boolean` — False disallow marks in code blocks by normalizing them away.
|
65 | - `getIndent: (Value) => string` — Returns the indent unit as a string. The current value is passed as context.
|
66 |
|
67 | #### Suppressing onKeyDown behavior
|
68 |
|
69 | Some behavior implemented by this plugins have no corresponding option. While there is an option `selectAll` to disable the behavior on `Mod+A`, If you would like to fine tune these behavior, you can always redefine the exported `onKeyDown` function.
|
70 |
|
71 | The following example disable all indent behavior
|
72 |
|
73 | ```js
|
74 | import EditCode from 'slate-edit-code'
|
75 |
|
76 | const options = { ... };
|
77 |
|
78 | const basePlugin = EditCode(options);
|
79 |
|
80 | const customPlugin = {
|
81 | ...basePlugin,
|
82 | onKeyDown(event, change, editor) {
|
83 | if (event.key === 'Tab') {
|
84 | // Bypass the original plugin behavior on `Tab`
|
85 | return;
|
86 | } else {
|
87 | return basePlugin.onKeyDown(event, change, editor);
|
88 | }
|
89 | }
|
90 | }
|
91 |
|
92 | // Use customPlugin later on
|
93 | ```
|
94 |
|
95 | ### Utilities and Changes
|
96 |
|
97 | `slate-edit-code` exports utilities, accessible like so:
|
98 |
|
99 | ``` js
|
100 | const plugin = EditCode()
|
101 |
|
102 | // Access exported utilities there
|
103 | plugin.utils
|
104 | ```
|
105 |
|
106 | #### `utils.deserializeCode`
|
107 |
|
108 | `plugin.utils.deserializeCode(text: String) => Block`
|
109 |
|
110 | Split a text string into lines, and deserialize them to a `code_container` `Block`, with one children `code_line` `Block` per line.
|
111 |
|
112 |
|
113 | #### `changes.toggleCodeBlock`
|
114 |
|
115 | `plugin.changes.toggleCodeBlock(change: Change, type: String) => Change`
|
116 |
|
117 | Toggle a block into a code block or a normal block (defined by `type`).
|
118 |
|
119 | #### `changes.wrapCodeBlockByKey`
|
120 |
|
121 | `plugin.changes.wrapCodeBlockByKey(change: Change, key: String) => Change`
|
122 |
|
123 | Convert a block (paragraph, etc) into a code block.
|
124 |
|
125 | #### `changes.wrapCodeBlock`
|
126 |
|
127 | `plugin.changes.wrapCodeBlock(change: Change) => Change`
|
128 |
|
129 | Convert current block (paragraph, etc) into a code block.
|
130 |
|
131 | #### `changes.unwrapCodeBlockByKey`
|
132 | `plugin.changes.unwrapCodeBlockByKey(change: Change, key: String, type: String) => Change`
|
133 |
|
134 | Convert a code block into a normal block (paragraph, etc).
|
135 |
|
136 | #### `changes.unwrapCodeBlock`
|
137 |
|
138 | `plugin.changes.unwrapCodeBlock(change: Change, type: String) => Change`
|
139 |
|
140 | Convert current code block into a normal block (paragraph, etc).
|