Update docs for 9.4.0

Author: estruyf

.frontmatter/database/mediaDb.json

@@ -17,6 +17,7 @@
 - [#709](https://github.com/estruyf/vscode-front-matter/issues/709): Take "where clause" into account on content creation
 - [#710](https://github.com/estruyf/vscode-front-matter/issues/710): Hide child field when parent field its "when clause" is not met, also remove the fields from the content
 - [#713](https://github.com/estruyf/vscode-front-matter/issues/713): Add the ability to always use quotes around string values in front matter
+- [#722](https://github.com/estruyf/vscode-front-matter/issues/722): Allow to create sub-content which shows a dialog to select the parent folder
 
 ### ⚡️ Optimizations
 

content/changelog/CHANGELOG.md

@@ -0,0 +1,115 @@
+---
+title: Version 9.4.0 release notes
+description: ""
+date: 2023-12-07T15:05:16.280Z
+lastmod: 2023-12-07T16:40:53.318Z
+slug: ""
+type: changelog
+---
+
+## Localization of Front Matter CMS
+
+Now both the webviews and the extension dialogs, messages, and notifications are localized. Currently we support the following languages:
+
+- German
+- Spanish
+- French
+- Italian
+- Japanese
+- Korean
+- Portuguese (Brazil)
+- English
+
+> **Important**: If a human translation is not available for the language, it will be translated using Azure Translation Services. This means that the translation might not be 100% accurate. In case you want to help us translate Front Matter CMS to your language, please check out the [localization documentation](/docs/contributing#translating-the-extension).
+
+## Custom script enhancements
+
+With the [@frontmatter/extensibility](https://www.npmjs.com/package/@frontmatter/extensibility) package, it is easier to create custom scripts for Front Matter CMS and it allows you to do more like asking questions to the user.
+
+### Getting the arguments
+
+Previously, you had to manually parse the arguments from the `process.argv` array. Now you can use the `getArguments` function from the `@frontmatter/extensibility` package.
+
+```ts
+import { ContentScript, MediaScript } from '@frontmatter/extensibility';
+
+// In content scripts
+const contentScriptArgs = ContentScript.getArguments();
+
+// In media scripts
+const mediaScriptArgs = MediaScript.getArguments();
+```
+
+> **Info**: More information can be found in the [creating a content script](/docs/custom-actions#creating-a-content-script) and [creating a media script](/docs/custom-actions#creating-a-media-script) documentation.
+
+### Asking questions
+
+You can now ask questions to the user when running a script. This can be done by using the `askQuestion` function from the `@frontmatter/extensibility` package.
+
+```ts
+import { MediaScript } from '@frontmatter/extensibility';
+
+const mediaScriptArgs = MediaScript.getArguments();
+
+const answers = mediaScriptArgs.answers;
+if (!answers) {
+  MediaScript.askQuestions([{
+    name: "width",
+    message: "What is the width of the image?",
+    default: image.width
+  }]);
+  return;
+}
+
+const width = answers.width;
+
+// Do something with the width
+```
+
+> **Info**: More information can be found in the [asking questions to users](/docs/custom-actions#asking-questions-to-users) documentation.
+
+### Scheduled content
+
+You can now filter and group the content dashboard by scheduled content. This allows you to see which content is scheduled to be published in the future.
+
+![Scheduled content](/releases/v9.4.0/scheduled-content.png)
+
+## Related issues/enhancements
+
+### ✨ New features
+
+- Localization implemented for the whole extension
+
+### 🎨 Enhancements
+
+- [#273](https://github.com/estruyf/vscode-front-matter/issues/273): Allow single value arrays to be set as a string with the `singleValueAsString` field property
+- [#686](https://github.com/estruyf/vscode-front-matter/issues/686): Allow script authors to ask questions during script execution
+- [#688](https://github.com/estruyf/vscode-front-matter/issues/688): Allow to show the scheduled articles in the content dashboard (filter and group)
+- [#690](https://github.com/estruyf/vscode-front-matter/issues/690): Added the ability to filter values in the `contentRelationship` field
+- [#700](https://github.com/estruyf/vscode-front-matter/issues/700): Added the `{{pathToken.relPath}}` placeholder for the `previewPath` property
+- [#706](https://github.com/estruyf/vscode-front-matter/issues/706): Show the error of scripts failing in the Front Matter output panel
+- [#709](https://github.com/estruyf/vscode-front-matter/issues/709): Take "where clause" into account on content creation
+- [#710](https://github.com/estruyf/vscode-front-matter/issues/710): Hide child field when parent field its "when clause" is not met, also remove the fields from the content
+- [#713](https://github.com/estruyf/vscode-front-matter/issues/713): Add the ability to always use quotes around string values in front matter
+- [#722](https://github.com/estruyf/vscode-front-matter/issues/722): Allow to create sub-content which shows a dialog to select the parent folder
+
+### ⚡️ Optimizations
+
+- Dashboard layout grid optimizations
+- Added the content-type name to the metadata section in the panel
+- New implementation of the combobox for the `contentRelationship` field
+
+### 🐞 Fixes
+
+- [#685](https://github.com/estruyf/vscode-front-matter/issues/685): Fix when using non-string values in the tag picker
+- [#691](https://github.com/estruyf/vscode-front-matter/issues/691): Silent authentication retrieval for GitHub sponsors
+- [#694](https://github.com/estruyf/vscode-front-matter/issues/694): Start terminal session from the folder where the `frontmatter.json` file is located
+- [#696](https://github.com/estruyf/vscode-front-matter/issues/696): Close the local server terminal on restart
+- [#699](https://github.com/estruyf/vscode-front-matter/issues/699): Changing border theme variable for the dashboard header
+- [#703](https://github.com/estruyf/vscode-front-matter/issues/703): Fix retrieval of Astro Collections for `pnpm` projects
+- [#704](https://github.com/estruyf/vscode-front-matter/issues/704): Fix `zod` schema script for optional fields
+- [#707](https://github.com/estruyf/vscode-front-matter/issues/707): Fix `clearEmpty` issue with `draft` and `boolean` fields which are by default set to `true`
+- [#711](https://github.com/estruyf/vscode-front-matter/issues/711): Fix in character mapping in the slug field
+- [#712](https://github.com/estruyf/vscode-front-matter/issues/712): Keep the search context when deleting media files
+- [#714](https://github.com/estruyf/vscode-front-matter/issues/714): Fix for taxonomy filtering from taxonomy view to content view
+- [#718](https://github.com/estruyf/vscode-front-matter/issues/718): Fix JSON schema for the `frontMatter.panel.actions.disabled` setting

content/changelog/v9.4.0.md

@@ -3,7 +3,7 @@ title: Custom actions
 slug: custom-actions
 description: null
 date: 2021-08-30T16:13:00.546Z
-lastmod: 2023-11-02T15:02:24.382Z
+lastmod: 2023-12-07T16:37:05.124Z
 weight: 500
 ---
 
@@ -93,7 +93,27 @@ The environment option contains the following properties:
 ## Creating a content script
 
 Create a folder in your project where you want to store all your custom scripts, and create a new
-JavaScript file. The sample content of this file looks like this:
+JavaScript file.
+
+> **Info**: You can also use another language like Python, Bash, ... for your script. Examples are
+> provided at the end of this page.
+
+### Installing the extensibility package (optional)
+
+When using JavaScript, you can make use of the
+[@frontmatter/extensibility](https://www.npmjs.com/package/@frontmatter/extensibility) package.
+
+```bash
+npm i @frontmatter/extensibility
+```
+
+With this `@frontmatter/extensibility` dependency,
+you can easily get the arguments and ask questions to the user.
+
+### Creating a script without the extensibility package
+
+When you do not want to use the `@frontmatter/extensibility` package, you can create a script as
+follows:
 
 ```javascript
 const arguments = process.argv;
@@ -107,25 +127,37 @@ if (arguments && arguments.length > 0) {
 }
 ```
 
-> **Info**: The sample script can be found here [sample-script.js][03]
-
 The current workspace-, file-path, and front matter data will be passed as a arguments. Like you can
 see in the above sample script, you can fetch these argument values as follows:
 
 - `arguments[2]`: The workspace path
 - `arguments[3]`: The file path (Markdown file)
 - `arguments[4]`: The front matter data as object
 
-In order to use this functionality, you will need to configure the `frontMatter.custom.scripts`
+### Creating a script with the extensibility package
+
+When you want to use the `@frontmatter/extensibility` package, you can create a script as follows:
+
+```javascript
+import { ContentScript } from "@frontmatter/extensibility";
+
+const { workspacePath, filePath, frontMatter, answers } = ContentScript.getArguments();
+
+ContentScript.done("The content returned for your notification.");
+```
+
+### Configure the script
+
+To use this functionality, you will need to configure the `frontMatter.custom.scripts`
 setting for your project as follows:
 
 ```json
 {
   "frontMatter.custom.scripts": [
     {
       "title": "Generate social image",
-      "script": "./scripts/social-img.js",
-      "command": "~/.nvm/versions/node/v14.15.5/bin/node"
+      "script": "./scripts/social-img.mjs",
+      "command": "~/.nvm/versions/node/v18.17.1/bin/node"
     }
   ]
 }
@@ -142,7 +174,7 @@ useful when you generate additional content.
 
 ![Custom action output][04]
 
-### Updating the front matter
+### Updating the front matter of your content
 
 By default, once a custom action executed, it will show the output in a notification. In case you
 want to update the front matter of your content, you need to provide the data in the following JSON
@@ -152,17 +184,17 @@ format.
 { "frontmatter": { "<field name>": "field value" } }
 ```
 
-Example:
+Example when you want to update the title without the `@frontmatter/extensibility` dependency:
 
-```javascript
+```javascript {{ "title": "Update without the extensibility dependency" }}
 (async () => {
     // Your script logic
 
     // Finally, update the front matter of your content by passing the data
     // in the following format
     const output = JSON.stringify({
-      "frontmatter": {
-        "title": "My new title"
+      frontmatter: {
+        title: "My new title"
       }
     });
 
@@ -171,6 +203,14 @@ Example:
 })();
 ```
 
+Example when you want to update the title with the `@frontmatter/extensibility` dependency:
+
+```javascript {{ "title": "Update with the extensibility dependency" }}
+import { ContentScript } from "@frontmatter/extensibility";
+
+ContentScript.updateFrontMatter({ title: "My new title" })
+```
+
 When data is passed in the above format, it will automatically get parse the JSON data and the file
 its front matter gets updated accordingly.
 
@@ -230,11 +270,19 @@ Here is a sample on how you can define a media script:
 }
 ```
 
-The current workspace-, file/folder-path will be passed as a arguments.
+The script will provide you the following arguments:
 
 - `arguments[2]`: The workspace path
 - `arguments[3]`: The file or folder path. This depends on the type of script.
 
+When using the `@frontmatter/extensibility` package, you can get the arguments as follows:
+
+```javascript
+import { MediaScript } from "@frontmatter/extensibility";
+
+const { workspacePath, mediaPath, answers } = MediaScript.getArguments();
+```
+
 ### Media file script
 
 When you defined a media file script, you will be able to execute it for a single media file from
@@ -249,6 +297,65 @@ menu next to the **create new folder** button.
 
 ![Custom action for a media folder][06]
 
+## Asking questions to users
+
+When you want to ask questions to the user, you can use the `askQuestions` function from the
+`@frontmatter/extensibility` package. This functionality can be used in both content and media
+scripts.
+
+To get started, you need to know that you have to check if the `answers` property is available in
+the arguments. If it is not available, you can ask the questions to the user. Once the user has
+answered the questions, the answers will be passed to the script.
+
+Here is a sample on how you can ask questions to the user:
+
+```javascript {{ "title": "Sample script with questions to the user" }}
+import { MediaScript } from '@frontmatter/extensibility';
+import { Image } from 'image-js';
+
+(async () => {
+  const mediaScriptArgs = MediaScript.getArguments();
+
+  if (!mediaScriptArgs) {
+    MediaScript.done(`No arguments found`);
+    return;
+  }
+  
+  const imagePath = mediaScriptArgs.mediaPath;
+  const answers = mediaScriptArgs.answers;
+
+  let image = await Image.load(imagePath);
+
+  if (!answers) {
+    MediaScript.askQuestions([{
+      name: "width",
+      message: "What is the width of the image?",
+      default: image.width
+    }]);
+    return;
+  }
+
+  const width = answers.width;
+
+  if (!width) {
+    MediaScript.done(`No width provided`);
+    return;
+  }
+
+  await image.resize({ width: parseInt(width) }).save(imagePath);
+
+  MediaScript.done(`Image resized to ${width}px`);
+})();
+```
+
+How the above script works:
+
+1. It will check if the `answers` property is available in the arguments. If it is not available,
+we create a new question for the user and return the script without any output.
+1. Once the user has answered the question, the script will be executed again, but this time the
+`answers` property will be available in the arguments.
+1. We will fetch the width from the answers and resize the image accordingly.
+
 ## Sample scripts
 
 ### Bash starter
@@ -336,7 +443,6 @@ const arguments = process.argv;
 
 [01]: /assets/custom-action.png
 [02]: https://www.eliostruyf.com/generate-open-graph-preview-image-code-front-matter/
-[03]: https://github.com/estruyf/vscode-front-matter/blob/HEAD/sample/script-sample.js
 [04]: /assets/custom-action-output.png
 [05]: /releases/v5.6.0/media-file-custom-script.png
-[06]: /releases/v5.6.0/media-folder-custom-script.png
+[06]: /releases/v9.4.0/media-folder-script.png