From a4260d7cbd8b39df2ecb5286b211a4ce8dd50d87 Mon Sep 17 00:00:00 2001 From: Aaron Junker-Wildi Date: Mon, 11 Dec 2023 16:45:16 +0100 Subject: [PATCH] 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> --- .github/actions/spell-check/expect.txt | 7 ++ doc/devdocs/common/FilePreviewCommon.md | 75 +++++++++++++++++++ doc/devdocs/{ => common}/common.md | 2 + doc/devdocs/common/readme.md | 7 ++ doc/devdocs/modules/peek/readme.md | 7 ++ .../modules/powerpreview/monaco/readme.md | 24 ------ 6 files changed, 98 insertions(+), 24 deletions(-) create mode 100644 doc/devdocs/common/FilePreviewCommon.md rename doc/devdocs/{ => common}/common.md (98%) create mode 100644 doc/devdocs/common/readme.md create mode 100644 doc/devdocs/modules/peek/readme.md delete mode 100644 doc/devdocs/modules/powerpreview/monaco/readme.md diff --git a/.github/actions/spell-check/expect.txt b/.github/actions/spell-check/expect.txt index db8bc0b780..6fb81c9ff7 100644 --- a/.github/actions/spell-check/expect.txt +++ b/.github/actions/spell-check/expect.txt @@ -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 diff --git a/doc/devdocs/common/FilePreviewCommon.md b/doc/devdocs/common/FilePreviewCommon.md new file mode 100644 index 0000000000..7293e8c978 --- /dev/null +++ b/doc/devdocs/common/FilePreviewCommon.md @@ -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. diff --git a/doc/devdocs/common.md b/doc/devdocs/common/common.md similarity index 98% rename from doc/devdocs/common.md rename to doc/devdocs/common/common.md index 48db53733b..5d5d906a44 100644 --- a/doc/devdocs/common.md +++ b/doc/devdocs/common/common.md @@ -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. diff --git a/doc/devdocs/common/readme.md b/doc/devdocs/common/readme.md new file mode 100644 index 0000000000..0ba4ef5b03 --- /dev/null +++ b/doc/devdocs/common/readme.md @@ -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. \ No newline at end of file diff --git a/doc/devdocs/modules/peek/readme.md b/doc/devdocs/modules/peek/readme.md new file mode 100644 index 0000000000..8bb73d62fc --- /dev/null +++ b/doc/devdocs/modules/peek/readme.md @@ -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). \ No newline at end of file diff --git a/doc/devdocs/modules/powerpreview/monaco/readme.md b/doc/devdocs/modules/powerpreview/monaco/readme.md deleted file mode 100644 index ac9ae3eae2..0000000000 --- a/doc/devdocs/modules/powerpreview/monaco/readme.md +++ /dev/null @@ -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.