Skip to content

Commit f29d48a

Browse files
subframe7536subframe7536
committed
docs: improve descriptions in package.json and README for clarity and consistency
1 parent 4bd8735 commit f29d48a

File tree

2 files changed

+85
-80
lines changed

2 files changed

+85
-80
lines changed

‎README.md

Lines changed: 60 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77
</p>
88
</p>
99

10-
Custom UI Style is a VSCode extension that modify CSS and JS code in editor and webview, unify global font family, setup background image and Electron BrowserWindow options, add your custom CSS or JS code, or patching file in other VSCode extensions
10+
Custom UI Style is a VSCode extension that allows you to customize the editor's appearance and behavior by injecting custom CSS and JavaScript. You can unify the global font family, set a background image, modify Electron `BrowserWindow` options, add your own custom styles and scripts, and even patch files in other VSCode extensions.
1111

1212
- Works with VSCode 1.103! (Tested on Windows and MacOS)
1313

@@ -21,28 +21,27 @@ Untested on Linux and VSCode forks (like Cursor, WindSurf, etc.), and I currentl
2121

2222
## Features
2323

24-
- Unified global font family
25-
- Setup background image
26-
- Custom nest stylesheet for both editor and webview
27-
- Custom Electron `BrowserWindow` options
28-
- [From V0.4.0] Support total restart
29-
- [From V0.4.0] Suppress corrupt message
30-
- [From V0.4.2] Load external CSS or JS file
31-
- [From V0.6.0] Patch files in extension
24+
- Unify the global font family for the editor and webviews.
25+
- Set a background image for the editor window.
26+
- Apply custom stylesheets to both the editor and webviews.
27+
- Configure Electron `BrowserWindow` options.
28+
- Support for restarting VSCode to apply changes.
29+
- Suppress the "Your Code installation is corrupt" message.
30+
- Load external CSS and JavaScript files.
31+
- Patch files in other extensions.
3232

3333
## Usage
3434

35-
When first installed or new VSCode version upgraded, the plugin will prompt to dump backup file.
35+
1. **Backup:** When you first install the extension or after a VSCode update, you'll be prompted to create a backup of the original files. This is important for rollback.
36+
2. **Configure:** Add your customizations to your `settings.json` file. See the [Example](#example) and [Configurations](#configurations) sections for details.
37+
3. **Apply:** Open the Command Palette (<kbd>Ctrl+Shift+P</kbd> or <kbd>Cmd+Shift+P</kbd>) and run `Custom UI Style: Reload` to apply your changes.
38+
4. **Rollback:** To revert all changes and restore the original VSCode files, run `Custom UI Style: Rollback` from the Command Palette.
3639

37-
After changing the configuration, please open command panel and run `Custom UI Style: Reload` to apply the configuration.
38-
39-
To rollback or uninstall the plugin, please open command panel and run `Custom UI Style: Rollback` to restore the original VSCode file.
40-
41-
See [details](https://github.com/shalldie/vscode-background?tab=readme-ov-file#warns)
40+
See [details](https://github.com/shalldie/vscode-background?tab=readme-ov-file#warns) for more information.
4241

4342
### Example
4443

45-
Avaiable CSS Variables:
44+
Available CSS Variables:
4645

4746
- `--cus-monospace-font`: Target monospace font family
4847
- `--cus-sans-font`: Target sans-serif font family
@@ -122,11 +121,13 @@ Avaiable CSS Variables:
122121

123122
### External Resources (CSS or JS File)
124123

125-
From v0.4.2, the extension supports loading external CSS or JS file from local file or remote URL. This operation may introduce security issue or runtime crash, use it with caution!
124+
Starting from v0.4.2, you can load external CSS and JavaScript files from local or remote URLs.
126125

127-
All resources will be applied in editor instead of webview.
126+
> [!caution]
127+
> Loading external resources can introduce security risks or cause runtime crashes. Use this feature with caution.
128128
129-
All resources will be fetched, merged and persist according to resource type during reload, so there is no watcher support.
129+
- All resources are applied to the editor, not webviews.
130+
- Resources are fetched and merged during reload. Live-watching of files is not supported.
130131

131132
```jsonc
132133
{
@@ -164,17 +165,17 @@ All resources will be fetched, merged and persist according to resource type dur
164165

165166
#### Load Strategy
166167

167-
By default, all resources will be refetched during every reload. Failed fetch will be skipped.
168+
By default, all resources are re-fetched on every reload, and failed fetches are skipped.
168169

169-
To skip refetching resources if there is nothing changed on `custom-ui-style.external.imports` and all resources are successfully fetched before, setup:
170+
To cache resources and avoid re-fetching when `custom-ui-style.external.imports` is unchanged, set the load strategy to `"cache"`:
170171

171172
```jsonc
172173
{
173174
"custom-ui-style.external.loadStrategy": "cache"
174175
}
175176
```
176177

177-
To disable all external resources, setup:
178+
To disable all external resources, set the load strategy to `"disable"`:
178179

179180
```jsonc
180181
{
@@ -206,41 +207,44 @@ Find and replace target string or `Regexp` in extension's file
206207

207208
## FAQ
208209

209-
### What is modified
210+
### What is modified?
210211

211-
ALL modifications are located in VSCode's installation directory, and modified files are backed up with `custom-ui-style` suffix in same directory. See all file paths in [path.ts](https://github.com/subframe7536/vscode-custom-ui-style/tree/main/src/path.ts)
212+
This extension modifies files in your VSCode installation directory. All modified files are backed up with a `.custom-ui-style` suffix in the same directory. You can see the full list of modified files in [`path.ts`](https://github.com/subframe7536/vscode-custom-ui-style/tree/main/src/path.ts).
212213

213-
When reload config, the extension will check backup file first, then read content from backup file and overwrite the original file with patches. Finally try to reload window or restart APP.
214+
When you reload the configuration, the extension restores the original files from the backup, applies your custom patches, and then reloads the window or restarts the application.
214215

215216
### No Effect
216217

217-
If you are using Windows or Linux, make sure you have closed all the VSCode windows and then restart.
218+
If your changes don't seem to apply, you may need to fully restart VSCode.
218219

219-
If you are using MacOS, press <kbd>Command + Q</kbd> first, then restart VSCode.
220+
- **Windows/Linux:** Close all VSCode windows and restart the application.
221+
- **macOS:** Press <kbd>Command + Q</kbd> to quit the application, then restart it.
220222

221-
There are [guide](https://github.com/subframe7536/vscode-custom-ui-style/issues/1#issuecomment-2423660217) and [video](https://github.com/subframe7536/vscode-custom-ui-style/issues/2#issuecomment-2432225106) (MacOS) of the process.
223+
There are also a [guide](https://github.com/subframe7536/vscode-custom-ui-style/issues/1#issuecomment-2423660217) and a [video](https://github.com/subframe7536/vscode-custom-ui-style/issues/2#issuecomment-2432225106) (macOS) available for more detailed instructions.
222224

223225
### EROFS: read-only file system
224226

225-
This extension need to modify VSCode's source code but VSCode runs on read-only filesystem (snap, AppImage...). Maybe you need to choose another way to install VSCode.
227+
If you see this error, it means VSCode is installed on a read-only filesystem (e.g., via Snap or AppImage). This extension needs to write to the installation directory, so you'll need to install VSCode using a different method.
226228

227229
### RangeError: Maximum call stack size exceeded
228230

229-
Due to system permission restrictions, maybe you will receive `RangeError: Maximum call stack size exceeded` prompt when you reload the configuration. You need to fully close VSCode first (press <kbd>Command + Q</kbd> on MacOS), then run:
231+
This error can occur due to system permission restrictions. To fix it, you need to change the ownership of the VSCode installation directory.
232+
233+
First, fully close VSCode (<kbd>Command + Q</_kbd> on macOS). Then, run the following command:
230234

231235
```sh
232-
# MacOS
236+
# macOS
233237
sudo chown -R $(whoami) "/Applications/Visual Studio Code.app"
234238

235239
# Linux
236240
sudo chown -R $(whoami) "/usr/local/code"
237241
```
238242

239-
See in [#6](https://github.com/subframe7536/vscode-custom-ui-style/issues/6)
243+
See [#6](https://github.com/subframe7536/vscode-custom-ui-style/issues/6) for more details.
240244

241245
### Fail to render panel
242246

243-
According to [#34](https://github.com/subframe7536/vscode-custom-ui-style/issues/34), in Cursor (close source VSCode's fork), the extension detail panel will not show by default due to the violation of iframe's CSP. Currently the way to fix it is just skip patch on webview, so please set:
247+
In some VSCode forks like Cursor, the extension detail panel may not render due to a Content Security Policy (CSP) violation. To work around this, you can disable the webview patch:
244248

245249
```json
246250
{
@@ -252,28 +256,29 @@ According to [#34](https://github.com/subframe7536/vscode-custom-ui-style/issues
252256

253257
<!-- configs -->
254258

255-
| Key | Description | Type | Default |
256-
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | ----------- |
257-
| `custom-ui-style.preferRestart` | Prefer to restart vscode after update instead of reload window only (ALWAYS true when VSCode version &gt;= 1.95.0) | `boolean` | `false` |
258-
| `custom-ui-style.reloadWithoutPrompting` | Reload/restart immediately, instead of having to click 'Reload Window' in the notification | `boolean` | `false` |
259-
| `custom-ui-style.watch` | Watch configuration changes and reload window automatically (ignore imports) | `boolean` | `true` |
260-
| `custom-ui-style.electron` | Electron BrowserWindow options | `object` | `{}` |
261-
| `custom-ui-style.font.monospace` | Global monospace font family that apply in both editor and webview, fallback to editor's font family | `string` | `` |
262-
| `custom-ui-style.font.sansSerif` | Global sans-serif font family that apply in both editor and webview | `string` | `` |
263-
| `custom-ui-style.background.url` | Full-screen background image url (will not sync), support protocol: 'https://', 'file://', 'data:' | `string` | `` |
264-
| `custom-ui-style.background.syncURL` | Full-screen background image url (will sync), support variable: [${userHome}, ${env:your_env_name:optional_fallback_value}], has lower priority than 'Url', support protocol: 'https://', 'file://', 'data:' | `string` | `` |
265-
| `custom-ui-style.background.opacity` | Background image opacity (0 ~ 1) | `number` | `0.9` |
266-
| `custom-ui-style.background.size` | Background image size | `string` | `"cover"` |
267-
| `custom-ui-style.background.position` | Background image position | `string` | `"center"` |
268-
| `custom-ui-style.external.loadStrategy` | Load strategy for external CSS or JS resources | `string` | `"refetch"` |
269-
| `custom-ui-style.external.imports` | External CSS or JS resources, support variable: [${userHome}, ${env:your_env_name:optional_fallback_value}], support protocol: 'https://', 'file://' | `array` | `` |
270-
| `custom-ui-style.stylesheet` | Custom css for editor, support nest selectors | `object` | `{}` |
271-
| `custom-ui-style.extensions` | Config to patch extension code, key is extension id, value is config | `object` | `{}` |
272-
| `custom-ui-style.webview.enable` | Enable style patch in webview | `boolean` | `true` |
273-
| `custom-ui-style.webview.removeCSP` | Remove Content-Security-Policy restrict in webview | `boolean` | `true` |
274-
| `custom-ui-style.webview.monospaceSelector` | Custom monospace selector in webview | `array` | `` |
275-
| `custom-ui-style.webview.sansSerifSelector` | Custom sans-serif selector in webview | `array` | `` |
276-
| `custom-ui-style.webview.stylesheet` | Custom css for webview, support nest selectors | `object` | `{}` |
259+
| Key | Description | Type | Default |
260+
| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | --------- | ----------- |
261+
| `custom-ui-style.preferRestart` | Prefer restarting VSCode after updates (always true for VSCode &gt;= 1.95.0) | `boolean` | `false` |
262+
| `custom-ui-style.reloadWithoutPrompting` | Reload/restart immediately without a notification prompt | `boolean` | `false` |
263+
| `custom-ui-style.watch` | Automatically reload window on configuration changes (ignores imports) | `boolean` | `true` |
264+
| `custom-ui-style.electron` | Electron BrowserWindow options (see Electron documentation) | `object` | `{}` |
265+
| `custom-ui-style.font.monospace` | Global monospace font family for editor and webviews (falls back to editor's font) | `string` | `` |
266+
| `custom-ui-style.font.sansSerif` | Global sans-serif font family for editor and webviews | `string` | `` |
267+
| `custom-ui-style.background.url` | Full-screen background image URL (e.g., 'https://', 'file://', 'data:') - not synced | `string` | `` |
268+
| `custom-ui-style.background.syncURL` | Full-screen background image URL (synced), supports variables like ${userHome} or ${env:VAR:fallback}. Lower priority than 'url'. | `string` | `` |
269+
| `custom-ui-style.background.opacity` | Background image opacity (0 to 1) | `number` | `0.9` |
270+
| `custom-ui-style.background.size` | Background image size (e.g., 'cover', 'contain') | `string` | `"cover"` |
271+
| `custom-ui-style.background.position` | Background image position | `string` | `"center"` |
272+
| `custom-ui-style.external.loadStrategy` | Strategy for loading external CSS or JS resources | `string` | `"refetch"` |
273+
| `custom-ui-style.external.imports` | External CSS or JS resources; supports variables (${userHome}, ${env:VAR:fallback}) and protocols ('https://', 'file://') | `array` | `` |
274+
| `custom-ui-style.stylesheet` | Custom CSS for the editor; supports nested selectors | `object` | `{}` |
275+
| `custom-ui-style.extensions.enable` | Enable file patching in other extensions | `boolean` | `true` |
276+
| `custom-ui-style.extensions.config` | Configuration for patching extension code (key: extension ID, value: patch config) | `object` | `{}` |
277+
| `custom-ui-style.webview.enable` | Enable style patching in webviews | `boolean` | `true` |
278+
| `custom-ui-style.webview.removeCSP` | Remove Content-Security-Policy restrictions in webviews | `boolean` | `true` |
279+
| `custom-ui-style.webview.monospaceSelector` | Custom monospace selector for webviews | `array` | `` |
280+
| `custom-ui-style.webview.sansSerifSelector` | Custom sans-serif selector for webviews | `array` | `` |
281+
| `custom-ui-style.webview.stylesheet` | Custom CSS for webviews; supports nested selectors | `object` | `{}` |
277282

278283
<!-- configs -->
279284

0 commit comments

Comments
 (0)