7 |
7 |
8 |
9 | # Usage
10 |
11 | ## Starting the add-on
12 |
13 | 
14 |
15 | ## Formatting inline code
16 |
17 | 
18 |
19 | ## Formatting code blocks
20 |
21 | 
22 |
23 | ## Reformatting code blocks
24 |
25 | 
26 |
27 | ## Previewing themes
28 |
29 | Examples of the different color themes applied to various languages can be
30 | found on the [highlight.js demo page](https://highlightjs.org/static/demo/).
31 |
32 | ## Unformatting code
33 |
34 | To clear formatting in Docs, highlight the text and select
35 | `Format > Clear Formatting` from the toolbar. The keyboard shortcut is
36 | Cmd+/ on OS X and Ctrl+/ on
37 | Windows:
38 | https://support.google.com/docs/answer/179738
39 |
40 | This will not remove the table that the text lives in if it's a "code block".
41 | To do that, you'll have to copy the text and paste it outside the table, then
42 | right-click the table and select **Delete table**.
43 |
44 | # Limitations
45 |
46 | ## Updates to syntax highlighting
47 |
48 | Code Blocks is built with [highlight.js](https://highlightjs.org/) and can only
49 | provide syntax highlighting for languages that are supported by that library.
50 |
51 | If you'd like to see Code Blocks support a language that is not yet implemented
52 | by highlight.js, please refer to [their page on requesting new languages](http://highlightjs.readthedocs.io/en/latest/language-requests.html).
53 |
54 | If you'd like to see Code Blocks update or fix support for an existing language:
55 | 1. Check if the [latest version of highlight.js](https://github.com/highlightjs/highlight.js/releases)
56 | already includes the update. If it does, submit a PR to this repository that
57 | bumps the highlight.js version in [`package.json`](https://github.com/alexwforsythe/code-blocks/blob/master/package.json).
58 | 2. If highlight.js does not yet include the update, please submit an issue on
59 | [their issue tracker](https://github.com/highlightjs/highlight.js/issues).
60 |
61 | ## Real-time syntax highlighting
62 |
63 | Codes Blocks uses Google's
64 | [Apps Script](https://developers.google.com/apps-script/), a server-side
65 | JavaScript platform, to interact with Docs and format code. Each time the add-on
66 | formats a snippet of code, a request is made to the Apps Script backend to
67 | modify the current Doc. There are a few limitations of this platform that
68 | prevent Code Blocks from formatting code as you type:
69 | * The [`onEdit`](https://developers.google.com/apps-script/guides/triggers#onedite)
70 | event that fires when a user modifies content is only available in Sheets
71 | * [Time-driven triggers](https://developers.google.com/apps-script/guides/triggers/installable#time-driven_triggers)
72 | can only be used once per hour at most
73 | * Each request to modify the current Doc can take multiple seconds, so code
74 | formatting cannot be performed in real-time
75 | * The number of requests needed to update a Doc in near real-time may exceed
76 | the service API quotas
77 |
78 | ## Keyboard Shortcuts
79 |
80 | Keyboard shortcuts can only be handled by Code Blocks if the add-on sidebar is
81 | focused, which would require users to click the sidebar anyway.
82 |
83 | Keyboard events in the active document cannot currently be handled by Docs
84 | add-ons:
85 | https://issuetracker.google.com/issues/79461369
86 |
87 | # Contributing
88 |
89 | ## Setup
90 |
91 | ```
92 | $ npm install
93 | ```
94 |
95 | ## Building
96 |
97 | ```
98 | $ npm run build
99 | ```
100 |
101 | ## Pushing Changes
102 |
103 | ℹ️ The following commands only work for the project maintainer
104 | because they require Google Drive authorization.
105 |
106 | | Command | Description |
107 | | --- | --- |
108 | | `npm run push:gas` | just GAS files |
109 | | `npm run push:js` | just `sidebar.js` |
110 | | `npm run push:static` | just HTML & CSS |
111 | | `npm run push` | everything |
112 |
113 | # Google Apps Script Resources
114 |
115 | * https://developers.google.com/apps-script/guides/clasp
116 | * https://github.com/google/clasp/blob/master/docs/typescript.md
117 | * https://developers.google.com/apps-script/guides/support/best-practices
118 | * https://gsuite-developers.googleblog.com/2015/12/advanced-development-process-with-apps.html
119 | * http://googleappsscript.blogspot.com/2010/06/optimizing-spreadsheet-operations.html
120 |
121 | ---
122 |
123 | [Homepage](https://www.alexwforsythe.com/code-blocks/) | [Google Workspace Marketplace](https://workspace.google.com/marketplace/app/code_blocks/100740430168) | [Privacy Policy](https://www.alexwforsythe.com/code-blocks/privacy-policy) | [Terms of Service](https://www.alexwforsythe.com/code-blocks/terms-of-service)
124 |
--------------------------------------------------------------------------------
/_config.yml:
--------------------------------------------------------------------------------
1 | theme: jekyll-theme-slate
--------------------------------------------------------------------------------
/appsscript.json:
--------------------------------------------------------------------------------
1 | {
2 | "timeZone": "America/Los_Angeles",
3 | "oauthScopes": [
4 | "https://www.googleapis.com/auth/documents.currentonly",
5 | "https://www.googleapis.com/auth/script.container.ui"
6 | ],
7 | "dependencies": {
8 | },
9 | "exceptionLogging": "STACKDRIVER"
10 | }
11 |
--------------------------------------------------------------------------------
/build.sh:
--------------------------------------------------------------------------------
1 | #!/usr/bin/env bash
2 |
3 | set -e
4 |
5 | dist_dir="dist"
6 | mkdir -p ${dist_dir}
7 |
8 | gas () {
9 | cp appsscript.json ${dist_dir}
10 | cp server/*.js ${dist_dir}
11 | }
12 |
13 | js () {
14 | # wrap bundled js in script tags and rename as html
15 | input_file="client/sidebar.js"
16 | output_file="${dist_dir}/bundle.min.js.html"
17 | echo "" >> ${output_file}
20 | }
21 |
22 | html () {
23 | cp client/*.html ${dist_dir}
24 | }
25 |
26 | css () {
27 | output_file="${dist_dir}/styles.html"
28 |
29 | optimizations="optimizeBackground:off;"
30 | optimizations+="replaceMultipleZeros:off;"
31 | optimizations+="specialComments:off"
32 |
33 | # wrap all theme css in style tags and bundle into html
34 | echo "" > ${output_file}
35 | for filename in node_modules/highlight.js/styles/*.css; do
36 | theme_name=$(basename "${filename}" .css)
37 | if [[ ${theme_name} != 'darkula' ]]; then
38 | theme=""
41 | echo ${theme} >> ${output_file}
42 | fi
43 | done
44 | echo "" >> ${output_file}
45 | }
46 |
47 | case "$1" in
48 | "gas") gas;;
49 | "js") js;;
50 | "html") html;;
51 | "css") css;;
52 | "static") html && css;;
53 | *)
54 | echo "invalid command: $1"
55 | exit 1
56 | ;;
57 | esac
58 |
--------------------------------------------------------------------------------
/client/logo.svg.html:
--------------------------------------------------------------------------------
1 |
8 |
--------------------------------------------------------------------------------
/client/sidebar.css.html:
--------------------------------------------------------------------------------
1 |
44 |
--------------------------------------------------------------------------------
/client/sidebar.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |