From e8640211a6b504b9d2838dcbf9b40a7a9e3d1b99 Mon Sep 17 00:00:00 2001 From: Greg Annandale Date: Tue, 31 Mar 2026 17:17:01 +0100 Subject: [PATCH] chore(docs): run eslint on docs --- .../docs/guides/app-integration/run-code.mdx | 90 ++++++++++------- .../guides/configure/web/appearance/css.mdx | 4 +- .../configure/web/configuration_struct.mdx | 2 +- .../guides/configure/web/customization.mdx | 2 +- .../guides/configure/web/translations.mdx | 10 +- .../contribute/samples/block_libraries.mdx | 99 +++++++++---------- .../fields/customizing-fields/creating.mdx | 2 +- .../guides/programming/plugin_overview.mdx | 90 +++++++++-------- .../guides/programming/using_blockly_apis.mdx | 12 +-- packages/docs/docs/reference/_reference.js | 6 +- packages/docs/eslint.config.mjs | 7 +- 11 files changed, 175 insertions(+), 149 deletions(-) diff --git a/packages/docs/docs/guides/app-integration/run-code.mdx b/packages/docs/docs/guides/app-integration/run-code.mdx index df06fc372..a13e75dd1 100644 --- a/packages/docs/docs/guides/app-integration/run-code.mdx +++ b/packages/docs/docs/guides/app-integration/run-code.mdx @@ -22,46 +22,62 @@ code generators with any of the following methods. - ```js import {javascriptGenerator} from 'blockly/javascript'; import{' '} - {pythonGenerator} from 'blockly/python'; import {phpGenerator} from - 'blockly/php'; import {luaGenerator} from 'blockly/lua'; import{' '} - {dartGenerator} from 'blockly/dart'; // Generate code for all the blocks in - the workspace. const jsCode = - javascriptGenerator.workspaceToCode(workspace); const pythonCode = - pythonGenerator.workspaceToCode(workspace); const phpCode = - phpGenerator.workspaceToCode(workspace); const luaCode = - luaGenerator.workspaceToCode(workspace); const dartCode = - dartGenerator.workspaceToCode(workspace); ``` + ```js + import {javascriptGenerator} from 'blockly/javascript'; + import {pythonGenerator} from 'blockly/python'; + import {phpGenerator} from 'blockly/php'; + import {luaGenerator} from 'blockly/lua'; + import {dartGenerator} from 'blockly/dart'; + + // Generate code for all the blocks in the workspace. + const jsCode = javascriptGenerator.workspaceToCode(workspace); + const pythonCode = pythonGenerator.workspaceToCode(workspace); + const phpCode = phpGenerator.workspaceToCode(workspace); + const luaCode = luaGenerator.workspaceToCode(workspace); + const dartCode = dartGenerator.workspaceToCode(workspace); + ``` - You must include the generator after you include Blockly. ```html - - - - - - - ``` ```js // Generate code for all the blocks in the workspace. const jsCode - = javascript.javascriptGenerator.workspaceToCode(workspace); const - pythonCode = python.pythonGenerator.workspaceToCode(workspace); const - phpCode = php.phpGenerator.workspaceToCode(workspace); const luaCode = - lua.luaGenerator.workspaceToCode(workspace); const dartCode = - dart.dartGenerator.workspaceToCode(workspace); ``` + You must include the generator after you include Blockly. + + ```html + + + + + + + ``` + + ```js + // Generate code for all the blocks in the workspace. + const jsCode = javascript.javascriptGenerator.workspaceToCode(workspace); + const pythonCode = python.pythonGenerator.workspaceToCode(workspace); + const phpCode = php.phpGenerator.workspaceToCode(workspace); + const luaCode = lua.luaGenerator.workspaceToCode(workspace); + const dartCode = dart.dartGenerator.workspaceToCode(workspace); + ``` - You must include the generator after you include Blockly. ```html - - - - - - - ``` ```js // Generate code for all the blocks in the workspace. const jsCode - = javascript.javascriptGenerator.workspaceToCode(workspace); const - pythonCode = python.pythonGenerator.workspaceToCode(workspace); const - phpCode = php.phpGenerator.workspaceToCode(workspace); const luaCode = - lua.luaGenerator.workspaceToCode(workspace); const dartCode = - dart.dartGenerator.workspaceToCode(workspace); ``` + You must include the generator after you include Blockly. + + ```html + + + + + + + ``` + + ```js + // Generate code for all the blocks in the workspace. + const jsCode = javascript.javascriptGenerator.workspaceToCode(workspace); + const pythonCode = python.pythonGenerator.workspaceToCode(workspace); + const phpCode = php.phpGenerator.workspaceToCode(workspace); + const luaCode = lua.luaGenerator.workspaceToCode(workspace); + const dartCode = dart.dartGenerator.workspaceToCode(workspace); + ``` ## Generate code @@ -105,7 +121,7 @@ start or after the end of the generated code. ```js let code = javascriptGenerator.workspaceToCode(workspace); // Add a preamble and a postscript to the code. -const preamble = "import {MyLibrary} from '/path/to/my/library';\n"; +const preamble = 'import {MyLibrary} from \'/path/to/my/library\';\n' const postscript = 'MyLibrary.myKickoffFunction();\n'; code = preamble + code + postscript; ``` diff --git a/packages/docs/docs/guides/configure/web/appearance/css.mdx b/packages/docs/docs/guides/configure/web/appearance/css.mdx index e729f134d..942d61e8a 100644 --- a/packages/docs/docs/guides/configure/web/appearance/css.mdx +++ b/packages/docs/docs/guides/configure/web/appearance/css.mdx @@ -175,7 +175,7 @@ lead to unpredictable results. If you understand SVG styling properties and the CSS cascade, you can [skip](#css-rules) this section. -### SVG styling properties versus CSS properties {#svg-style} +### SVG styling properties versus CSS properties \{#svg-style\} SVG elements are styled with [SVG styling properties](https://developer.mozilla.org/en-US/docs/Web/SVG/Reference/Attribute#presentation_attributes). @@ -233,7 +233,7 @@ more than one rule applies to a given property and element. The following simplified cascade covers the parts of the cascade most commonly used by Blockly and may help you resolve the question, "Why doesn't my CSS work?" -#### Simplified cascade {#simplified} +#### Simplified cascade \{#simplified\} To determine which rule applies to a particular element and property, follow these steps and stop when only one rule remains: diff --git a/packages/docs/docs/guides/configure/web/configuration_struct.mdx b/packages/docs/docs/guides/configure/web/configuration_struct.mdx index bc76ff377..9a33599b5 100644 --- a/packages/docs/docs/guides/configure/web/configuration_struct.mdx +++ b/packages/docs/docs/guides/configure/web/configuration_struct.mdx @@ -33,7 +33,7 @@ configuration options in a call to `new Blockly.Options(options)` -- the `WorkspaceSvg` constructor cannot accept your configuration options object directly. -## Configuration options{#the-options-dictionary} +## Configuration options \{#the-options-dictionary\} The configuration object implements [`Blockly.BlocklyOptions`](/reference/blockly.blocklyoptions_interface) diff --git a/packages/docs/docs/guides/configure/web/customization.mdx b/packages/docs/docs/guides/configure/web/customization.mdx index 7e5093835..93ca1029c 100644 --- a/packages/docs/docs/guides/configure/web/customization.mdx +++ b/packages/docs/docs/guides/configure/web/customization.mdx @@ -81,7 +81,7 @@ Blockly.registry.register( ); ``` -### Inject your replacement class {#injecting-subclasses} +### Inject your replacement class \{#injecting-subclasses\} You can also inject replacement classes using the `plugins` [configuration option](/guides/configure/web/configuration_struct#the-options-dictionary). diff --git a/packages/docs/docs/guides/configure/web/translations.mdx b/packages/docs/docs/guides/configure/web/translations.mdx index 04cf2b369..c1af5436c 100644 --- a/packages/docs/docs/guides/configure/web/translations.mdx +++ b/packages/docs/docs/guides/configure/web/translations.mdx @@ -71,7 +71,7 @@ want to support and whether you plan to support more locales in the future. 1. [Load the Blockly localization table](#load-blockly) for the locale. 1. [Load your localization table](#load-custom) for the locale. -## Define and use localization tokens {#define} +## Define and use localization tokens \{#define\} When supporting multiple locales, you need to define and use localization tokens for all of your custom text. @@ -220,7 +220,7 @@ references in JavaScript: displayText: () => '%{BKY_MY_CONTEXT_MENU_ITEM}'; ``` -## Choose a locale {#choose} +## Choose a locale \{#choose\} How to choose a locale is application-specific and outside the scope of Blockly. For example, your application might always use the same locale, determine the @@ -233,7 +233,7 @@ the workspace: Blockly does not update the existing toolbox or blocks to use the new locale automatically. To preserve the user's work (if any), save the state before you re-create the workspace and re-load it after. -## Load a Blockly localization table {#load-blockly} +## Load a Blockly localization table \{#load-blockly\} Blockly provides localization tables for all of its own text, such as the text on built-in blocks. Unless you are using the `en` locale, which is loaded by @@ -288,7 +288,7 @@ load the table from the `msg` directory. For example: The localization table is loaded automatically. -## Load your own localization table {#load-custom} +## Load your own localization table \{#load-custom\} If you define your own localization tables, you need to load the table for your chosen locale. @@ -343,7 +343,7 @@ registration](/guides/create-custom-blocks/fields/customizing-fields/creating#js [Translating](/guides/contribute/core/translating) in the section on contributing to Blockly. -## Appendix: Where token references are allowed {#where} +## Appendix: Where token references are allowed \{#where\} You can use [token references](#use-localization-tokens-in-json) in the following JSON keys: diff --git a/packages/docs/docs/guides/contribute/samples/block_libraries.mdx b/packages/docs/docs/guides/contribute/samples/block_libraries.mdx index 562b2fb0b..2c414147a 100644 --- a/packages/docs/docs/guides/contribute/samples/block_libraries.mdx +++ b/packages/docs/docs/guides/contribute/samples/block_libraries.mdx @@ -14,6 +14,7 @@ import CompareBlock from '@site/src/components/CompareBlock'; /> + # Publish block libraries Plugins that provide libraries of block definitions are a great way to share @@ -22,27 +23,28 @@ versatile and useful as possible, we've developed these guidelines. ## Guidelines -- Make it **easy** for users to install all of your blocks, and make it - **possible** for users to install only certain blocks or pieces of blocks - they choose. - - Make it easy to install everything: You can do this by providing a - function that installs every piece a single block definition requires - (such as mutators, extensions, mixins, fields, etc.). You can also - provide a function that will install all of the blocks offered by your - plugin at once. - - Make it possible to choose specific parts: You should export all of the - pieces of a block definition separately, so that it is possible for a - user to import only the pieces they need in order to create their own - similar custom block. -- Avoid using side effects in your plugin. - - Blocks, fields, extensions, and other pieces shouldn't be installed as a - side effect of loading your plugin. Users should maintain control over - which things are installed and when. This allows users to import the - pieces they need without worrying that pieces they don't will be - installed. -- Use the JSON field registry instead of instantiating new fields directly. - - -Not Recommended - Instantiating a new field directly: +- Make it **easy** for users to install all of your blocks, and make it + **possible** for users to install only certain blocks or pieces of blocks + they choose. + - Make it easy to install everything: You can do this by providing a + function that installs every piece a single block definition requires + (such as mutators, extensions, mixins, fields, etc.). You can also + provide a function that will install all of the blocks offered by your + plugin at once. + - Make it possible to choose specific parts: You should export all of the + pieces of a block definition separately, so that it is possible for a + user to import only the pieces they need in order to create their own + similar custom block. +- Avoid using side effects in your plugin. + - Blocks, fields, extensions, and other pieces shouldn't be installed as a + side effect of loading your plugin. Users should maintain control over + which things are installed and when. This allows users to import the + pieces they need without worrying that pieces they don't will be + installed. +- Use the JSON field registry instead of instantiating new fields directly. + + - + Not Recommended - Instantiating a new field directly: ```js const myCustomBlock = { @@ -52,11 +54,10 @@ Not Recommended - Instantiating a new field directly: } } ``` + - - - - -Recommended - JSON field registry: + - + Recommended - JSON field registry: ```js export const myCustomBlock = { @@ -69,36 +70,34 @@ Recommended - JSON field registry: } } ``` + - - - - Using the field registry makes it easier for a user to replace the - implementation of the field used in your block without having to change + - Using the field registry makes it easier for a user to replace the + implementation of the field used in your block without having to change the block definition. - -- Don't make assumptions about what the user has already installed. - - If your plugin requires a custom field or another plugin, register those +- Don't make assumptions about what the user has already installed. + - If your plugin requires a custom field or another plugin, register those fields yourself in your provided `install` function. - - Soon, Blockly will provide tools that let you register - already-registered items without error. Until then, you may want to - check what has already been registered before registering an extension, + - Soon, Blockly will provide tools that let you register + already-registered items without error. Until then, you may want to + check what has already been registered before registering an extension, mutator, mixin, or field yourself. - - Be clear about any prerequisites or dependencies that are required by - your plugin or block definitions. -- Consider providing generator functions for each of the blocks you provide. - - Providing generator functions that work out of the box makes it easier - for users to use your blocks without having to understand their - structure and design. If they have to write their own generator - functions, this may lead to redundant work being done by each user. - - JavaScript is the most commonly used language in Blockly, so if you only + - Be clear about any prerequisites or dependencies that are required by + your plugin or block definitions. +- Consider providing generator functions for each of the blocks you provide. + - Providing generator functions that work out of the box makes it easier + for users to use your blocks without having to understand their + structure and design. If they have to write their own generator + functions, this may lead to redundant work being done by each user. + - JavaScript is the most commonly used language in Blockly, so if you only pick one language to provide, we recommend JavaScript, unless your blocks - are built for a specific language such as implementing a Python library. - - Consider posting 'help wanted' issues for languages for which you are - unable to implement generator functions, and accept pull requests for - these if a user contributes them. - - If you provide an install function for your block, you can accept an - optional `generators` parameter. If a user passes a generator instance - that you support, you can automatically install the block-code generator + are built for a specific language such as implementing a Python library. + - Consider posting 'help wanted' issues for languages for which you are + unable to implement generator functions, and accept pull requests for + these if a user contributes them. + - If you provide an install function for your block, you can accept an + optional `generators` parameter. If a user passes a generator instance + that you support, you can automatically install the block-code generator function and do related work such as adding reserved words: ```js diff --git a/packages/docs/docs/guides/create-custom-blocks/fields/customizing-fields/creating.mdx b/packages/docs/docs/guides/create-custom-blocks/fields/customizing-fields/creating.mdx index 79988d9db..65a35c897 100644 --- a/packages/docs/docs/guides/create-custom-blocks/fields/customizing-fields/creating.mdx +++ b/packages/docs/docs/guides/create-custom-blocks/fields/customizing-fields/creating.mdx @@ -860,7 +860,7 @@ set to `true`. This is not the case by default for backwards compatibility reasons. ::: -## Customizing with CSS{#css} +## Customizing with CSS \{#css\} You can customize your field with CSS. In the [`initView` method](#on-block-display), add a custom class to your field's `fieldGroup_`, diff --git a/packages/docs/docs/guides/programming/plugin_overview.mdx b/packages/docs/docs/guides/programming/plugin_overview.mdx index 146945d99..6885af3cf 100644 --- a/packages/docs/docs/guides/programming/plugin_overview.mdx +++ b/packages/docs/docs/guides/programming/plugin_overview.mdx @@ -41,46 +41,52 @@ applications. ## Find a plugin -- Visit [Blockly Plugins & - Demos](https://raspberrypifoundation.github.io/blockly-samples/#plugins), which has live - demos of first-party plugins. +* Visit [Blockly Plugins & + Demos](https://raspberrypifoundation.github.io/blockly-samples/#plugins), which has live + demos of first-party plugins. -- Search npm for - [`keyword:blockly-plugin`](https://www.npmjs.com/search?q=keyword%3Ablockly-plugin). - Plugins with the scope `@blockly` are published by the Blockly team. For - broader results, search for - [`keyword:blockly`](https://www.npmjs.com/search?q=keyword%3Ablockly) or - [`blockly`](https://www.npmjs.com/search?q=blockly). +* Search npm for + [`keyword:blockly-plugin`](https://www.npmjs.com/search?q=keyword%3Ablockly-plugin). + Plugins with the scope `@blockly` are published by the Blockly team. For + broader results, search for + [`keyword:blockly`](https://www.npmjs.com/search?q=keyword%3Ablockly) or + [`blockly`](https://www.npmjs.com/search?q=blockly). -- See the [`blockly-samples/plugins` - directory](https://github.com/RaspberryPiFoundation/blockly-samples/tree/main/plugins) on - GitHub, which is the repository for first-party plugins. Each plugin has a - README that describes its behaviour and intended use. +* See the [`blockly-samples/plugins` + directory](https://github.com/RaspberryPiFoundation/blockly-samples/tree/main/plugins) on + GitHub, which is the repository for first-party plugins. Each plugin has a + README that describes its behaviour and intended use. ## Install a plugin We recommend installing plugins with a package manager like npm or yarn. This makes it easy to receive updates. -- **Install a plugin with a package manager** - - - ```shell npm install @blockly/field-angle ``` - - - ```shell yarn add @blockly/field-angle ``` - - -- **Install a plugin without a package manager** - - +* **Install a plugin with a package manager** + + + ```shell + npm install @blockly/field-angle + ``` + + + ```shell + yarn add @blockly/field-angle + ``` + + +* **Install a plugin without a package manager** + + ```html - ``` You can also clone the GitHub repository that contains the plugin. For + ``` + + You can also clone the GitHub repository that contains the plugin. For first-party plugins, this is [`blockly-samples`](https://github.com/RaspberryPiFoundation/blockly-samples/tree/main). - - + + Check the plugin's README to see if there are any additional installation instructions. @@ -96,14 +102,18 @@ plugin](https://www.npmjs.com/package/@blockly/field-angle): the plugin. - ```js import Blockly from 'blockly'; import {registerFieldAngle} from - '@blockly/field-angle'; ``` + ```js + import Blockly from 'blockly'; + import {registerFieldAngle} from '@blockly/field-angle'; + ``` - You do not need to use an `import` statement. + You do not need to use an `import` statement. - ```js import {registerFieldAngle} from 'path/to/plugin'; ``` + ```js + import {registerFieldAngle} from 'path/to/plugin'; + ``` 1. Initialize the plugin as needed. Plugins that provide custom fields often @@ -118,27 +128,23 @@ plugin](https://www.npmjs.com/package/@blockly/field-angle): ```js Blockly.common.defineBlocksWithJsonArray([ { - type: 'my_angle_block', - message0: '%1 degrees', + type: "my_angle_block", + message0: "%1 degrees", args0: [ { // Use @blockly/field-angle. - type: 'field_angle', - name: 'FIELDNAME', + type: "field_angle", + name: "FIELDNAME", value: 45, }, ], output: null, - style: 'math_blocks', + style: 'math_blocks' }, ]); ``` - A field for picking an angle from a 360-degree dial. + A field for picking an angle from a 360-degree dial. ## Plugin versions diff --git a/packages/docs/docs/guides/programming/using_blockly_apis.mdx b/packages/docs/docs/guides/programming/using_blockly_apis.mdx index 86e8e10eb..5c588f51e 100644 --- a/packages/docs/docs/guides/programming/using_blockly_apis.mdx +++ b/packages/docs/docs/guides/programming/using_blockly_apis.mdx @@ -11,7 +11,7 @@ properties in core Blockly. These principles apply to creating [plugins](/guides/programming/plugin_overview) for Blockly and to integrating Blockly into a standalone application. -## Visibility {#visibility} +## Visibility \{#visibility\} We use [TypeScript access modifiers](https://www.typescriptlang.org/docs/handbook/2/classes.html#member-visibility) @@ -29,7 +29,7 @@ should avoid accessing anything that is not `public`. The Blockly team does not guarantee stability of non-public properties and functions between releases. ::: -### public {#annotations-public} +### public \{#annotations-public\} Anything marked `public` is part of our public API. Any property in a module that does not have a visibility modifier is considered public. @@ -42,7 +42,7 @@ consider a public function or property stable. Public functions may be called from anywhere, and overridden in subclasses as long as the signature does not change. -### protected {#annotations-protected} +### protected \{#annotations-protected\} Protected functions and properties may only be accessed by the defining class or a subclass. @@ -56,7 +56,7 @@ its protected properties. In each case you should make sure you understand how the function or property is used in the rest of the code. -### private {#annotations-private} +### private \{#annotations-private\} These can only be accessed by code in the same file as the definition. Directly accessing these properties may result in undefined behaviour. @@ -80,7 +80,7 @@ code. In rare cases private functions were used so widely that they became public, so you may see public functions that end in an underscore. ::: -### internal {#annotations-internal} +### internal \{#annotations-internal\} Internal functions and properties are intended to be used within the core library, but not externally. They are designated with the TsDoc `@internal` @@ -93,7 +93,7 @@ Internal properties may be accessed from anywhere within core, and overridden in subclasses in core as long as the signature does not change. They must not be accessed from outside of the core library. -### deprecated {#annotations-deprecated} +### deprecated \{#annotations-deprecated\} Anything marked `@deprecated` should not be used. Most deprecations include directions on the preferred code, either in a console warning or TSDoc. diff --git a/packages/docs/docs/reference/_reference.js b/packages/docs/docs/reference/_reference.js index 14ae63dd7..0b5a57693 100644 --- a/packages/docs/docs/reference/_reference.js +++ b/packages/docs/docs/reference/_reference.js @@ -1,7 +1,7 @@ export const referenceSidebar = [ { - "type": "doc", - "label": "Overview", - "id": "reference/blockly" + type: 'doc', + label: 'Overview', + id: 'reference/blockly', }, ]; diff --git a/packages/docs/eslint.config.mjs b/packages/docs/eslint.config.mjs index 8181a9bb5..33fee652a 100644 --- a/packages/docs/eslint.config.mjs +++ b/packages/docs/eslint.config.mjs @@ -20,6 +20,11 @@ export default [ }, }, { - ignores: ['docs/reference/**', 'build/**', '.docusaurus/**', 'node_modules/**'], + ignores: [ + 'docs/reference/**', + 'build/**', + '.docusaurus/**', + 'node_modules/**', + ], }, ];