mirror of
https://github.com/microsoft/PowerToys
synced 2024-11-22 00:03:48 +00:00
Add information about how to add new languages to monaco (#24906)
* Add information about how to add new languages to monaco * Update expect.txt * Update doc/devdocs/modules/FileExplorer/monaco/readme.md Co-authored-by: Jay <65828559+Jay-o-Way@users.noreply.github.com> * Adress PR feedback * fix spelling errors * Update doc/devdocs/modules/FileExplorer/monaco/readme.md Co-authored-by: Heiko <61519853+htcfreek@users.noreply.github.com> * Update readme.md * Update readme.md * Address PR comments * Fix spelling * address PR comments * address PR comments and move files * Update expect.txt * Update doc/devdocs/common/readme.md Co-authored-by: Heiko <61519853+htcfreek@users.noreply.github.com> * Update doc/devdocs/common/FilePreviewCommon.md Co-authored-by: Heiko <61519853+htcfreek@users.noreply.github.com> * Update doc/devdocs/common/FilePreviewCommon.md Co-authored-by: Heiko <61519853+htcfreek@users.noreply.github.com> * Update doc/devdocs/common/FilePreviewCommon.md Co-authored-by: Heiko <61519853+htcfreek@users.noreply.github.com> * Update doc/devdocs/common/FilePreviewCommon.md Co-authored-by: Heiko <61519853+htcfreek@users.noreply.github.com> * Update doc/devdocs/common/FilePreviewCommon.md Co-authored-by: Stefan Markovic <57057282+stefansjfw@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Stefan Markovic <57057282+stefansjfw@users.noreply.github.com> * Adress PR comments * Fix spelling * Adress PR comments * Add peek stub documentation * Update doc/devdocs/common/FilePreviewCommon.md Co-authored-by: Stefan Markovic <57057282+stefansjfw@users.noreply.github.com> * Update doc/devdocs/common/FilePreviewCommon.md * Fix spelling --------- Co-authored-by: Jay <65828559+Jay-o-Way@users.noreply.github.com> Co-authored-by: Heiko <61519853+htcfreek@users.noreply.github.com> Co-authored-by: Stefan Markovic <57057282+stefansjfw@users.noreply.github.com>
This commit is contained in:
Aaron Junker-Wildi
GitHub
parent
93a422ca9b
commit
a4260d7cbd
7
.github/actions/spell-check/expect.txt
vendored
7
.github/actions/spell-check/expect.txt
vendored
@ -745,6 +745,10 @@ killrunner
|
||||
Knownfolders
|
||||
KSPROPERTY
|
||||
Kybd
|
||||
LAlt
|
||||
Lambson
|
||||
languagesjson
|
||||
langword
|
||||
lastcodeanalysissucceeded
|
||||
Lastdevice
|
||||
LAYOUTRTL
|
||||
@ -1016,6 +1020,7 @@ NOTSRCCOPY
|
||||
NOTSRCERASE
|
||||
NOZORDER
|
||||
NPH
|
||||
npmjs
|
||||
NResize
|
||||
nrw
|
||||
nsunt
|
||||
@ -1708,6 +1713,8 @@ wcsnicmp
|
||||
WDA
|
||||
wdp
|
||||
wdupenv
|
||||
weakme
|
||||
webbrowsers
|
||||
webcam
|
||||
webpage
|
||||
websites
|
||||
|
||||
75
doc/devdocs/common/FilePreviewCommon.md
Normal file
75
doc/devdocs/common/FilePreviewCommon.md
Normal file
@ -0,0 +1,75 @@
|
||||
# [FilePreviewCommon](/src/common/FilePreviewCommon)
|
||||
|
||||
This project contains common code used for previewing and displaying files.
|
||||
|
||||
## Monaco preview
|
||||
|
||||
Monaco preview enables to display developer files. It is based on [Microsoft's Monaco Editor](https://microsoft.github.io/monaco-editor/) which is maintained by the Visual Studio Code team.
|
||||
|
||||
This previewer is used for the File Explorer Dev File Previewer, as well as PowerToys Peek.
|
||||
|
||||
### Update Monaco Editor
|
||||
|
||||
1. Download Monaco editor with [npm](https://www.npmjs.com/): Run `npm i monaco-editor` in the command prompt.
|
||||
2. Delete everything except the `min` folder (the minimised code) from the downloaded files.
|
||||
3. Copy the `min` folder into the `src/common/FilePreviewCommon/Assets/Monaco/monacoSRC` folder of the PowerToys project.
|
||||
4. Generate the JSON file as described in the generate [monaco_languages.json file](#monaco_languagesjson) section.
|
||||
|
||||
### Add a new language definition
|
||||
|
||||
As an example on how to add a new language definition you can look at the one for [registry files](/src/common/FilePreviewCommon/Assets/Monaco/customLanguages/reg.js).
|
||||
|
||||
1. Add the new language definition (written with [Monarch](https://microsoft.github.io/monaco-editor/monarch.html)) as a new file to the [folder containing Monaco custom languages](/src/common/FilePreviewCommon/Assets/Monaco/customLanguages/) (Remember the file name and the string you used for "idDefinition" as you need it later.). The file should be formatted like in the example below. (Please change `idDefinition` to the name of your language.)
|
||||
|
||||
```javascript
|
||||
export function idDefinition() {
|
||||
return {
|
||||
...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
2. Add the following line to the [`monacoSpecialLanguages.js`](/src/common/FilePreviewCommon/Assets/Monaco/monacoSpecialLanguages.js) file, after the other import statements:
|
||||
|
||||
```javascript
|
||||
import { idDefinition } from './customLanguages/file.js';
|
||||
```
|
||||
|
||||
> Replace file.js with the name of your definition file from step 1. Please replace idDefinition with the string you used in step 1.
|
||||
|
||||
3. In the [`monacoSpecialLanguages.js`](/src/common/FilePreviewCommon/Assets/Monaco/monacoSpecialLanguages.js) file add the following line into the `registerAdditionalLanguages` function:
|
||||
|
||||
```javascript
|
||||
registerAdditionalNewLanguage("id", [".fileExtension"], idDefinition(), monaco)
|
||||
```
|
||||
|
||||
> Replace id and idDefinition with your id and string used in step 1. Replace fileExtension with a set of file extensions you want the language to register to.
|
||||
|
||||
* The id can be anything. Recommended is one of the file extensions. For example "php" or "reg".
|
||||
|
||||
4. Execute the steps described in the [monaco_languages.json](#monaco_languagesjson) section.
|
||||
|
||||
### Add a new file extension to an existing language
|
||||
|
||||
1. In the [`monacoSpecialLanguages.js`](/src/common/FilePreviewCommon/Assets/Monaco/monacoSpecialLanguages.js) file add the following line to the `registerAdditionalLanguages` function. (`existingId` is the id of the language you want to add the extension to. You can find these id's in the [`monaco_languages.json`](/src/common/FilePreviewCommon/Assets/Monaco/monaco_languages.json) file):
|
||||
|
||||
```javascript
|
||||
registerAdditionalLanguage("id", [".fileExtension"], "existingId", monaco)
|
||||
```
|
||||
|
||||
* If for instance you want to add more extensions to the php language set the id to `phpExt` and the existingId to `php`.
|
||||
|
||||
2. Copy the existing language definition into the `languageDefinitions` function in the same file. You can find the existing definitions in the following folder: [`/src/common/FilePreviewCommon/Assets/Monaco/monacoSRC/min/vs/basic-languages/`](/src/common/FilePreviewCommon/Assets/Monaco/monacoSRC/min/vs/basic-languages/).
|
||||
|
||||
3. Execute the steps described in the [monaco_languages.json](#monaco_languagesjson) section.
|
||||
|
||||
### monaco_languages.json
|
||||
|
||||
[`monaco_languages.json`](/src/common/FilePreviewCommon/Assets/Monaco/monaco_languages.json) contains all extensions and IDs for the languages supported by Monaco. The [`MonacoHelper`](/src/common/FilePreviewCommon/MonacoHelper.cs) class and the installer are using this file to register preview handlers for the defined extensions.
|
||||
|
||||
After updating Monaco Editor and/or adding a new language you should update the [`monaco_languages.json`](/src/common/FilePreviewCommon/Assets/Monaco/monaco_languages.json) file.
|
||||
|
||||
1. Run the [`generateLanguagesJson.html`](/src/common/FilePreviewCommon/Assets/Monaco/generateLanguagesJson.html) file on a local webserver (as webbrowsers will block certain needed features when running the file locally.)
|
||||
* This can for example be achieved by using the [Preview Server](https://marketplace.visualstudio.com/items?itemName=yuichinukiyama.vscode-preview-server) extension for Visual Studio Code: Open the file in Visual Studio Code, right click in the code editor and select `vscode-preview-server: Launch on browser`. The file will be opened in a browser.
|
||||
2. The browser will download the new `monaco_languages.json` file
|
||||
3. Replace the old file with the newly downloaded one in the source code folder.
|
||||
@ -1,5 +1,7 @@
|
||||
# Classes and structures
|
||||
|
||||
> This document is outdated and will soon be renewed.
|
||||
|
||||
#### class Animation: [header](/src/common/animation.h) [source](/src/common/animation.cpp)
|
||||
Animation helper class with two easing-in animations: linear and exponential.
|
||||
|
||||
7
doc/devdocs/common/readme.md
Normal file
7
doc/devdocs/common/readme.md
Normal file
@ -0,0 +1,7 @@
|
||||
# Common
|
||||
|
||||
The [common](/src/common) folder contains projects with code, that is used in multiple projects.
|
||||
|
||||
## [FilePreviewCommon](FilePreviewCommon.md)
|
||||
|
||||
This project contains common code for file previewing.
|
||||
7
doc/devdocs/modules/peek/readme.md
Normal file
7
doc/devdocs/modules/peek/readme.md
Normal file
@ -0,0 +1,7 @@
|
||||
# PowerToys Peek
|
||||
|
||||
> Documentation is currently under construction
|
||||
|
||||
## Dev file previewer
|
||||
|
||||
The previewer for developer files uses the project in [FileExplorerCommon] common project to render monaco. You can find its documentation here: [/doc/devdocs/common/FilePreviewCommon.md](/doc/devdocs/common/FilePreviewCommon.md).
|
||||
@ -1,24 +0,0 @@
|
||||
# Developer Preview (Monaco)
|
||||
|
||||
Developer preview is based on [Microsoft's Monaco Editor](https://microsoft.github.io/monaco-editor/) which is maintained by the Visual Studio Code team.
|
||||
|
||||
## Update monaco editor
|
||||
|
||||
1. Download Monaco editor with npm: `npm i monaco-editor`.
|
||||
2. Delete everything except the `min` folder (the minimised code).
|
||||
3. Copy the `min` folder inside the [`monacoSRC`](/src/modules/previewpane/MonacoPreviewHandler/monacoSRC) folder.
|
||||
4. Generate the JSON file (see section below)
|
||||
|
||||
## monaco_languages.json
|
||||
|
||||
[`monaco_languages.json`](/src/modules/previewpane/MonacoPreviewHandler/monaco_languages.json) contains all extensions and Id's for the supported languages of Monaco. The [`FileHandler`](/src/modules/previewpane/MonacoPreviewHandler/FileHandler.cs) class and the installer are using this file.
|
||||
|
||||
### Generate monaco_languages.json file
|
||||
|
||||
After you updated monaco editor or adding a new language you should update the [`monaco_languages.json`](/src/modules/previewpane/MonacoPreviewHandler/monaco_languages.json) file.
|
||||
|
||||
You have to run the file on a local webserver!
|
||||
|
||||
1. Build monaco in debug mode.
|
||||
2. Open [generateLanguagesJson.html](/src/modules/previewpane/MonacoPreviewHandler/generateLanguagesJson.html) in a browser.
|
||||
3. Replace the old JSON file.
|
||||
Loading…
Reference in New Issue
Block a user