Skip to content

Commit 7b96565

Browse files
estruyfestruyf
committed
Update custom actions docs
1 parent dee1e53 commit 7b96565

21 files changed

+707
-18
lines changed

‎.frontmatter/database/mediaDb.json

Lines changed: 1 addition & 1 deletion
Large diffs are not rendered by default.

‎content/changelog/CHANGELOG.md

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Change Log
22

3-
## [10.3.0] - 2024-xx-xx
3+
## [10.3.0] - 2024-xx-xx - [Release notes](https://beta.frontmatter.codes/updates/v10.3.0)
44

55
### ✨ New features
66

@@ -23,6 +23,10 @@
2323
- [#830](https://github.com/estruyf/vscode-front-matter/issues/830): Fix for using the SEO title field setting to change the title field reference
2424
- [#832](https://github.com/estruyf/vscode-front-matter/issues/832): Fix for finding folders with wildcards in the path
2525

26+
## [10.2.1] - 2024-08-08
27+
28+
- [#820](https://github.com/estruyf/vscode-front-matter/issues/820): Update API links to the new API URL
29+
2630
## [10.2.0] - 2024-06-12 - [Release notes](https://beta.frontmatter.codes/updates/v10.2.0)
2731

2832
### ✨ New features

‎content/changelog/v10.3.0.md

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
---
2+
title: Version 10.3.0 release notes
3+
description: ""
4+
date: 2024-08-12T14:16:11.167Z
5+
lastmod: 2024-08-12T14:35:37.260Z
6+
slug: v10.3.0
7+
fmContentType: changelog
8+
---
9+
10+
## Added open in VS Code button to the documentation
11+
12+
Inside the documentation, we have added a new button to open certain areas from Front Matter CMS directly in VS Code. This helps you to quickly navigate to the right place in your project.
13+
14+
![Open in VS Code button on the documentation](/releases/v10.3.0/vscode-button-in-docs.webp)
15+
16+
## Select all media and content items in current view
17+
18+
In the content and media dashboards, we have added a new button to select all items in the current view. This makes it easier to perform bulk actions on multiple items.
19+
20+
![Select all items](/releases/v10.3.0/select-all.webp)
21+
22+
## Extensibility: Ability to copy metadata or delete media files
23+
24+
Our extensibility library has been extended with new actions which allow you to copy metadata or delete media files. This can be useful when you want to perform certain actions like for example convert a meda file to a different format and keep the metadata.
25+
26+
New actions:
27+
28+
- `MediaScript.copyMetadata(source, destination)`
29+
- `MediaScript.copyMetadataAndDelete(source, destination)`
30+
- `MediaScript.delete(source)`
31+
32+
## Related issues/enhancements
33+
34+
### ✨ New features
35+
36+
- [#823](https://github.com/estruyf/vscode-front-matter/issues/823): Integrated GitHub Copilot support for titles, descriptions, and tags
37+
- [#824](https://github.com/estruyf/vscode-front-matter/issues/824): Added the ability to link custom actions to fields
38+
39+
### 🎨 Enhancements
40+
41+
- [#467](https://github.com/estruyf/vscode-front-matter/issues/467): New `fmContentType` metadata field to link content type (fallback to the `type` field)
42+
- [#819](https://github.com/estruyf/vscode-front-matter/issues/819): Added new extensibility support for media scripts
43+
- [#820](https://github.com/estruyf/vscode-front-matter/issues/820): Moving the website and API to different hosts
44+
- [#821](https://github.com/estruyf/vscode-front-matter/issues/821): Added URI handler to support command links from the documentation
45+
- [#822](https://github.com/estruyf/vscode-front-matter/issues/822): Added docs to the panel & dashboard views
46+
- [#829](https://github.com/estruyf/vscode-front-matter/issues/829): UI extensibility is now generally available
47+
- [#831](https://github.com/estruyf/vscode-front-matter/issues/831): Added "select all" action bar button to the content and media dashboards
48+
49+
### 🐞 Fixes
50+
51+
- [#827](https://github.com/estruyf/vscode-front-matter/issues/827): Fix for `frontmatter.json` file which gets created when already present in a sub-folder
52+
- [#830](https://github.com/estruyf/vscode-front-matter/issues/830): Fix for using the SEO title field setting to change the title field reference
53+
- [#832](https://github.com/estruyf/vscode-front-matter/issues/832): Fix for finding folders with wildcards in the path

‎content/docs/ai/index.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
title: AI features
3+
slug: ai-features
4+
description: null
5+
date: 2024-08-13T07:26:50.054Z
6+
lastmod: 2024-08-13T08:04:06.136Z
7+
weight: 880
8+
---
9+
10+
- Copilot integration
11+
- Custom field commands

‎content/docs/custom-actions/advanced.md

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
---
2+
title: Advanced script actions
3+
slug: custom-actions/advanced
4+
description: null
5+
date: 2024-08-12T14:42:34.817Z
6+
lastmod: 2024-08-13T07:50:28.315Z
7+
weight: 500.3
8+
---
9+
10+
# Advanced script actions
11+
12+
In addition to the basic script actions, you can also use more advanced script actions to interact
13+
with the user, ask questions, or execute scripts in bulk.
14+
15+
## Asking questions
16+
17+
In case you need more information from a user to execute a script, you can ask questions using the
18+
`askQuestions` method from the `ContentScript` or `MediaScript` class.
19+
20+
You could for instance use this functionality to ask the user where they want to share an article,
21+
what the width and height of an image should be, or any other question you want to ask.
22+
Here is an example of how you can ask a question:
23+
24+
```javascript {{ "title": "Ask questions" }}
25+
import { ContentScript } from "@frontmatter/extensibility";
26+
27+
(() => {
28+
const contentScriptArgs = ContentScript.getArguments();
29+
if (!contentScriptArgs) {
30+
contentScriptArgs.done(`No arguments found`);
31+
return;
32+
}
33+
34+
// Retrieve the answers from the arguments
35+
const { answers } = contentScriptArgs;
36+
if (!answers) {
37+
// No answers found, ask the user
38+
ContentScript.askQuestions([{
39+
name: "platform",
40+
message: "Where do you want to share the article?",
41+
options: ["Twitter", "LinkedIn"]
42+
}]);
43+
// No further script execution is needed, the user will be prompted with the question
44+
return;
45+
}
46+
47+
// Once the user answered the question, the script will be executed again
48+
// with the answers provided by the user
49+
ContentScript.done(`You selected ${answers.platform}`);
50+
})();
51+
```
52+
53+
When you run the script, the user will be prompted with the question "Where do you want to share the
54+
article?" and can select either "Twitter" or "LinkedIn".
55+
56+
![Ask a question via the extensibility library][01]
57+
58+
## Bulk execution
59+
60+
If you want, you can run a script for multiple content files at once. This is useful when you want to
61+
generate a social image for all your markdown files or perform any other bulk operation.
62+
63+
To enable bulk script execution, you need to configure the `frontMatter.custom.scripts` setting for
64+
your project as follows:
65+
66+
```json {{ "title": "Bulk script configuration" }}
67+
{
68+
"frontMatter.custom.scripts": [
69+
{
70+
"title": "Generate social image",
71+
"script": "./scripts/social-img.js",
72+
"command": "~/.nvm/versions/node/v16.13.0/bin/node",
73+
"bulk": true,
74+
"output": "editor"
75+
}
76+
]
77+
}
78+
```
79+
80+
> **Info**: Since the introduction of the actions bar, you can now also select all items in the current
81+
> view and run content or media scripts for all selected items.
82+
83+
<!-- Link References -->
84+
85+
[01]: /releases/v10.3.0/extensibility-ask-question.webp

‎content/docs/custom-actions/content-scripts.md

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
---
2+
title: Content scripts
3+
slug: custom-actions/content-scripts
4+
description: null
5+
date: 2024-08-12T14:42:34.817Z
6+
lastmod: 2024-08-13T07:40:16.340Z
7+
weight: 500.1
8+
---
9+
10+
# Content scripts
11+
12+
A content script is a script that can be executed on a single or multiple content files.
13+
You can use this to generate additional content, update the front matter, or perform any other
14+
operation you want.
15+
16+
Start by creating a new folder in your project where you want to store all your custom scripts.
17+
In this folder, you can create a new script file.
18+
19+
> **Info**: You can also use languages like JavaScript, Python, Bash, ... for your script. Examples are
20+
> provided at the end of this page.
21+
22+
## Creating a new script
23+
24+
> **Important**: When using JavaScript, you can make use of the `@frontmatter/extensibility` library.
25+
> More information to install it can be found in the
26+
> [Extensibility library][02] section.
27+
28+
With the `@frontmatter/extensibility` package, you can create a script as follows:
29+
30+
```javascript {{ "title": "Example content script" }}
31+
import { ContentScript } from "@frontmatter/extensibility";
32+
33+
const { workspacePath, filePath, frontMatter, answers } = ContentScript.getArguments();
34+
35+
ContentScript.done("The content returned for your notification.");
36+
```
37+
38+
At the end of the script, you can call the `ContentScript.done` method to return a notification to the
39+
user or use any of the other methods provided by the `ContentScript` class.
40+
41+
| Method | Description |
42+
| --- | --- |
43+
| `ContentScript.done(message)` | Returns a notification to the user. |
44+
| `ContentScript.updateFrontMatter(data)` | Updates the front matter of the content file. |
45+
46+
## Configure the script
47+
48+
To use this functionality, you will need to configure the `frontMatter.custom.scripts`
49+
setting for your project as follows:
50+
51+
```json {{ "title": "Custom action configuration" }}
52+
{
53+
"frontMatter.custom.scripts": [
54+
{
55+
"title": "Generate social image",
56+
"script": "./scripts/social-img.mjs",
57+
"command": "~/.nvm/versions/node/v18.17.1/bin/node"
58+
}
59+
]
60+
}
61+
```
62+
63+
> **Important**: When the command execution would fail when it cannot find the node command. You are
64+
> able to specify your path to the node app. Command execution might for instance fail when using
65+
> `nvm`. You can use the `command` property to specify the path to your node executable (_this is
66+
> optional_).
67+
68+
Once a custom action has been configured, it will appear on the Front Matter panel. The output of
69+
the script will be passed as a notification in VS Code. This output allows you to copy the output,
70+
useful when you generate additional content.
71+
72+
![Custom action output][01]
73+
74+
## Update the front matter
75+
76+
By default, once a custom action executed, it will show the output in a notification.
77+
78+
In case you want to update the front matter of your content, you can use the `ContentScript.updateFrontMatter`
79+
method.
80+
81+
```javascript {{ "title": "Update with the extensibility dependency" }}
82+
import { ContentScript } from "@frontmatter/extensibility";
83+
84+
ContentScript.updateFrontMatter({ title: "My new title" })
85+
```
86+
87+
When data is passed in the above format, it will automatically get parse the JSON data and the file
88+
its front matter gets updated accordingly.
89+
90+
<!-- Link References -->
91+
92+
[01]: /assets/custom-action-output.png
93+
[02]: /docs/custom-actions#extensibility-library

‎content/docs/custom-actions/index.md

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
---
2+
title: Custom actions/scripts
3+
slug: custom-actions
4+
description: null
5+
date: 2021-08-30T16:13:00.546Z
6+
lastmod: 2024-08-12T14:58:47.310Z
7+
weight: 500
8+
---
9+
10+
# Custom actions and scripts
11+
12+
## Overview
13+
14+
<!-- markdownlint-disable MD013 MD033 -->
15+
<div class="iframe__wrapper">
16+
<iframe src="https://www.youtube.com/embed/wvH9Tn5LQ2c" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
17+
</div>
18+
<!-- markdownlint-enable MD013 MD033 -->
19+
20+
Not every website is the same. That is why we want to give you the ability to extend Front Matter
21+
and you can do this by adding your custom actions to the Front Matter panel. A custom action is
22+
nothing more than a Node.js script which is referenced from within your project.
23+
24+
![Custom action][01]
25+
26+
## Settings
27+
28+
The content and media custom actions can be defined by using the `frontMatter.custom.scripts` setting.
29+
30+
Custom actions can be configured with the following properties:
31+
32+
| Title | Type | Description | Default |
33+
| -------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
34+
| `id` | `string` | The id of the custom action/script | `""` |
35+
| `title` | `string` | The title of the custom action | `""` |
36+
| `script` | `string` | The path to the script to execute | `""` |
37+
| `command` | `string` | The command to execute (optional). Example: `node`, `path to your node executable`, `bash`, `python`, ... | `node` |
38+
| `type` | `<content \| mediaFile \| mediaFolder>` | The type for which the script will be used (optional). <br /><br /> Use one of the following types: `content`, `mediaFile`, or `mediaFolder`. | `content` |
39+
| `bulk` | `boolean` | Run the script for one file or multiple files. | `false` |
40+
| `output` | `<notification \| editor` | Specifies the output type (optional). <br /><br /> Available values are: `notification` and `editor`. <br /><br /> `notification`: The output will be passed as a notification. <br /> `editor`: The output will be passed to the editor. | `notification` |
41+
| `outputType` | `<text \| html>` | Specifies the output type (optional). <br /><br /> Available values the editor values from VS Code like: <br /><br /> `text`: The output will be passed as a text file. <br /> `html`: The output will be passed as an HTML file. <br /> `markdown`: The output will be passed as a Markdown file. | `text` |
42+
| `hidden` | `boolean` | Hide the action from the UI. This is mostly used when creating a content script that will be used to post process new content (optional). | `false` |
43+
| `environments` | `environment` | The environments option allows you to specify in which environments the script should be executed (optional). <br /><br /> Available values are: `macos`, `linux`, or `windows`. | `undefined` |
44+
| `contentTypes` | `string[]` | The content types for which the script will be used (optional). <br /><br /> Example: `["post"]` | `undefined` |
45+
46+
> **Important**: Previously, you could define the `nodeBin` property to define the path to your node
47+
> executable. This path was needed when you are working with for instance `nvm` and have multiple
48+
> versions of node installed. You can now use the `command` property instead.
49+
50+
### Environment type
51+
52+
The environment option contains the following properties:
53+
54+
| Title | Type | Description | Default |
55+
| --------- | ----------------------------- | --------------------------------------------------------------------------------------------------------- | ------- |
56+
| `type` | `<macos \| linux \| windows>` | The environment type for the script to run at. | `""` |
57+
| `script` | `string` | The path to the script to execute. | `""` |
58+
| `command` | `string` | The command to execute (optional). Example: `node`, `path to your node executable`, `bash`, `python`, ... | `node` |
59+
60+
#### Example of defining a custom action with an environment
61+
62+
```json {{ "title": "Custom action configuration" }}
63+
{
64+
"frontMatter.custom.scripts": [
65+
{
66+
"title": "Create image folder",
67+
"id": "create-image-folder",
68+
"script": "./.frontmatter/config/custom/scripts/create-image-folder.sh",
69+
"command": "bash",
70+
"environments": [
71+
{
72+
"type": "windows",
73+
"script": "./.frontmatter/config/custom/scripts/create-image-folder.ps1",
74+
"command": "powershell"
75+
}
76+
]
77+
}
78+
]
79+
}
80+
```
81+
82+
> **Info**: The above sample would execute the bash script on macOS and Linux and the PowerShell for
83+
> Windows. In case the PowerShell script would fail, it would fallback to the bash script.
84+
85+
## Extensibility library
86+
87+
The [@frontmatter/extensibility](https://www.npmjs.com/package/@frontmatter/extensibility) library
88+
provides you with the necessary methods to interact with the Front Matter CMS.
89+
90+
You can use the library for your custom actions to update the front matter of your content or media files.
91+
92+
### Installing the extensibility library
93+
94+
When using JavaScript, you can make use of the
95+
[@frontmatter/extensibility](https://www.npmjs.com/package/@frontmatter/extensibility) package.
96+
97+
```bash {{ "title": "Install the extensibility package" }}
98+
npm i @frontmatter/extensibility
99+
```
100+
101+
With this `@frontmatter/extensibility` dependency,
102+
you can easily get the arguments and ask questions to the user.
103+
104+
<!-- Link References -->
105+
106+
[01]: /assets/custom-action.png

0 commit comments

Comments
 (0)