Skip to content

Commit da33712

Browse files
michaeltlombardimichaeltlombardi
committed
(GH-11) Migrate to reference links
Prior to this change, all of the links in the Markdown documents were inline links. This could make parsing paragraphs difficult and meant in some cases that links were repeated, requiring them to be updated in multiple places if the URLs changed in the future. This change migrates the markdown link syntax to reference link syntax, placing the reference link definitions at the bottom of each file. It uses a two-digit order-of-appearance numbering, where links are defined as `[foo][01]` and `[bar][02]`. This limits the space used by the link references while also allowing reuse. A possible alternative would be to leave the image links as inline, but this change standardizes the links across every file and link type. While this change was performed manually, it should be possible in the future to use a scripted action or the continually improving options to [extract link definitions][01] and [organize link definitions][02] in the Markdown support for VS Code. [01]: https://code.visualstudio.com/updates/v1_72#_extract-to-link-definition-for-markdown [02]: https://code.visualstudio.com/updates/v1_72#_organize-link-definitions-in-markdown
1 parent 8e81486 commit da33712

19 files changed

+344
-193
lines changed

‎README.md

+11-7
Original file line numberDiff line numberDiff line change
@@ -2,23 +2,27 @@
22

33
This is the Front Matter its documentation respository.
44

5-
![Banner view of Front Matter, showing the extension with the a heading that reads "Headless CMD running in VS Code"](./public/releases/v4_0_0/banner-v2.png)
5+
![Banner view of Front Matter, showing the extension with the a heading that reads "Headless CMD running in VS Code"][01]
66

77
## Main documentation
88

9-
The documentation of the main Front Matter version can be found at
10-
[frontmatter.codes](https://frontmatter.codes).
9+
The documentation of the main Front Matter version can be found at [frontmatter.codes][02].
1110

1211
## BETA docs
1312

14-
The documentation of the BETA Front Matter version can be found at
15-
[beta.frontmatter.codes](https://beta.frontmatter.codes).
13+
The documentation of the BETA Front Matter version can be found at [beta.frontmatter.codes][03].
1614

1715
## Issues/Feedback
1816

1917
Please add issues or feedback of the Front Matter extension in the following repository:
20-
[Front Matter repository](https://github.com/estruyf/vscode-front-matter).
18+
[Front Matter repository][04].
2119

2220
## Contributions
2321

24-
Contributions to the documentation are always welcome!
22+
Contributions to the documentation are always welcome!
23+
24+
<!-- Link References -->
25+
[01]: ./public/releases/v4_0_0/banner-v2.png
26+
[02]: https://frontmatter.codes
27+
[03]: https://beta.frontmatter.codes
28+
[04]: https://github.com/estruyf/vscode-front-matter

‎content/docs/commands.md

+4-1
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ weight: 900
1414
Front Matter actions are also available as commands. In this section of the documentation all
1515
commands will be explained.
1616

17-
![Commands](/assets/commands-v6.1.0.png)
17+
![Commands][01]
1818

1919
## Using commands
2020

@@ -172,3 +172,6 @@ ID: `frontMatter.promoteSettings`
172172
This command has been removed, as it became obsolete since the introduction of Content Types.
173173

174174
ID: `frontMatter.setDate`
175+
176+
<!-- Link References -->
177+
[01]: /assets/commands-v6.1.0.png

‎content/docs/content-creation/content-type.md

+20-13
Original file line numberDiff line numberDiff line change
@@ -110,21 +110,21 @@ Adapt the fields to your needs. For our documentation it looks as follows:
110110

111111
The metadata section on the editor panel will render the following fields:
112112

113-
![Adapted default content type fields](/assets/adapted-default-ct.png)
113+
![Adapted default content type fields][01]
114114

115115
### Content type properties
116116

117117
For the content type you can configure the following properties:
118118

119-
| Property | Type | Description | Default value |
120-
| ------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
121-
| `name` | `string` | Name of the content type | `""` |
122-
| `fields` | `array` | Check the [supported field types](/docs/content-creation/fields#supported-field-types) | `[]` |
123-
| `fileType` | Enum: `md, mdx, markdown, <your choice>` | File type of for the content type you define. The type will be used to create the file when creating content. | `md` |
124-
| `pageBundle` | `boolean` | If set to `true`, the content will be created as a page bundle (folder). | `false` |
125-
| `previewPath` | `string` | Defines a custom preview path for the content type. When the preview path is not set, the value from the [frontMatter.preview.pathName](https://frontmatter.codes/docs/settings#frontmatter.preview.pathname) setting will be used. | `null` |
126-
| `template` | `string` | Specify a path to a template file that will be used when creating new content with the content type. | `null` |
127-
| `postScript` | `string` | An optional post script that can be used after new content creation. In order to use this, you will have to set the value to the ID of your [content script](/docs/custom-actions/#content-script). | `null` |
119+
| Property | Type | Description | Default value |
120+
| ------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
121+
| `name` | `string` | Name of the content type | `""` |
122+
| `fields` | `array` | Check the [supported field types][02] | `[]` |
123+
| `fileType` | Enum: `md, mdx, markdown, <your choice>` | File type of for the content type you define. The type will be used to create the file when creating content. | `md` |
124+
| `pageBundle` | `boolean` | If set to `true`, the content will be created as a page bundle (folder). | `false` |
125+
| `previewPath` | `string` | Defines a custom preview path for the content type. When the preview path is not set, the value from the [frontMatter.preview.pathName][03] setting will be used. | `null` |
126+
| `template` | `string` | Specify a path to a template file that will be used when creating new content with the content type. | `null` |
127+
| `postScript` | `string` | An optional post script that can be used after new content creation. In order to use this, you will have to set the value to the ID of your [content script][04]. | `null` |
128128

129129
## Define your own type
130130

@@ -175,8 +175,7 @@ type: documentation
175175
---
176176
```
177177

178-
> **Fields**: Check out the [fields](/docs/content-creation/fields) section to learn which fields
179-
> are supported.
178+
> **Fields**: Check out the [fields][05] section to learn which fields are supported.
180179
181180
## Using a template with the content type
182181

@@ -234,4 +233,12 @@ In your custom script setting, you need to make sure that this script is availab
234233
```
235234

236235
> **Info**: More information about custom scripts can be found in the
237-
> [custom actions](/docs/custom-actions) section.
236+
> [custom actions][06] section.
237+
238+
<!-- Link References -->
239+
[01]: /assets/adapted-default-ct.png
240+
[02]: /docs/content-creation/fields#supported-field-types
241+
[03]: https://frontmatter.codes/docs/settings#frontmatter.preview.pathname
242+
[04]: /docs/custom-actions/#content-script
243+
[05]: /docs/content-creation/fields
244+
[06]: /docs/custom-actions

‎content/docs/content-creation/fields.md

+44-27
Original file line numberDiff line numberDiff line change
@@ -39,15 +39,15 @@ There are also the following section fields:
3939

4040
All fields share the following field properties:
4141

42-
| Property | Type | Description | Optional / Required |
43-
| ------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
44-
| `name` | `string` | The name of your field, will be used to set in the front matter of your Markdown file. | **Required** |
45-
| `type` | `string` | The type of the field. Use one of the supported field types. | **Required** |
46-
| `title` | `string` | The title to show in the metadata section | _Optional_ |
47-
| `description` | `string` | The description to show underneath the field | _Optional_ |
48-
| `default` | `string` | Defines the default value for the field when creating the content type. You can also use placeholders like `{{title}}`, `{{slug}}` or `{{now}}`. Check for more information under [placeholders](/docs/content-creation/placeholders). | _Optional_ |
49-
| `required` | `boolean` | Defines if the field is required or not. If set to true, and the user does not define a value, a notification will appear. You can disable this notification with the [frontMatter.global.disabledNotifications](/docs/settings#frontmatter.global.disablednotifications) setting. | _Optional_ |
50-
| `hidden` | `boolean` | Specifies if you want to hide the field from the metadata section, but still have it available in Front Matter. | _Optional_ |
42+
| Property | Type | Description | Optional / Required |
43+
| ------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
44+
| `name` | `string` | The name of your field, will be used to set in the front matter of your Markdown file. | **Required** |
45+
| `type` | `string` | The type of the field. Use one of the supported field types. | **Required** |
46+
| `title` | `string` | The title to show in the metadata section | _Optional_ |
47+
| `description` | `string` | The description to show underneath the field | _Optional_ |
48+
| `default` | `string` | Defines the default value for the field when creating the content type. You can also use placeholders like `{{title}}`, `{{slug}}` or `{{now}}`. Check for more information under [placeholders][01]. | _Optional_ |
49+
| `required` | `boolean` | Defines if the field is required or not. If set to true, and the user does not define a value, a notification will appear. You can disable this notification with the [frontMatter.global.disabledNotifications][02] setting. | _Optional_ |
50+
| `hidden` | `boolean` | Specifies if you want to hide the field from the metadata section, but still have it available in Front Matter. | _Optional_ |
5151

5252
## String
5353

@@ -61,7 +61,7 @@ use if for the title, description, or any other text field.
6161
- `wysiwyg (boolean)`: When you set this value to `true`, the field will be rendered as a WYSIWYG
6262
editor. The output of the WYSIWYG editor will be HTML.
6363

64-
![WYSIWYG controls](/releases/v7.2.0/wysiwyg-controls.png)
64+
![WYSIWYG controls][03]
6565

6666
### Usage
6767

@@ -119,7 +119,7 @@ other types of dates for you content.
119119
article, this field will be used.
120120

121121
> The format of your date can be defined in the `frontMatter.taxonomy.dateFormat` setting. Check
122-
> [date-fns formating](https://date-fns.org/v2.0.1/docs/format) for more information.
122+
> [date-fns formating][04] for more information.
123123
124124
### Usage
125125

@@ -264,12 +264,11 @@ alias:
264264

265265
The `draft` field defines the state of your content. This is used for the content dashboard as well.
266266
By default, the draft field is a boolean. If you want to use your own status values, you can
267-
configure it via the
268-
[frontmatter.content.draftfield](/docs/settings#frontmatter.content.draftfield) setting.
267+
configure it via the [frontmatter.content.draftfield][05] setting.
269268

270269
When using a custom draft status, the content dashboard will make use of it as well:
271270

272-
![Draft filters](/releases/v5.3.0/draft-status.png)
271+
![Draft filters][06]
273272

274273
> **Important**: If you use Jekyll, you do not have to use the draft field, as Front Matter supports
275274
> the `_drafts`, `_posts` folders and collections from Jekyll. If you use Jekyll, make sure to set
@@ -439,7 +438,7 @@ The `tags` field allows you to create or use tags from your `frontMatter.taxonom
439438
default, none existing). When adding a tag which does not yet exist, you will have the option to
440439
create it.
441440

442-
![Add a new tag](/assets/tag-creation.png)
441+
![Add a new tag][07]
443442

444443
When the tag is created, you will be able to re-use it for other content.
445444

@@ -453,7 +452,7 @@ When the tag is created, you will be able to re-use it for other content.
453452

454453
> **Info**: When a limit is defined, this will get reflected in the UI as well:
455454
456-
![Taxonomy limit](/assets/tags-limit.png)
455+
![Taxonomy limit][08]
457456

458457
### Usage
459458

@@ -479,9 +478,8 @@ tags:
479478

480479
## Categories
481480

482-
The `categories` field is similar to the [tags](/docs/content-creation/fields#tags) field. The
483-
difference is that it uses the `frontMatter.taxonomy.categories` setting (by default, none
484-
existing).
481+
The `categories` field is similar to the [tags][09] field. The difference is that it uses the
482+
`frontMatter.taxonomy.categories` setting (by default, none existing).
485483

486484
### Properties
487485

@@ -563,7 +561,7 @@ customTags:
563561

564562
The `fields` field, allows you to create multi-dimensional content type fields (sub-fields). This is
565563
useful when you want to create a complex content type. In case you want to define a list data, you
566-
will have to use the [block](/docs/content-creation/fields#block) field.
564+
will have to use the [block][10] field.
567565

568566
When you specify the field type as `fields`, you need to define sub-fields within the `fields`
569567
property.
@@ -607,7 +605,7 @@ property.
607605

608606
### Outcome
609607

610-
![Multi-dimensional content type fields](/releases/v6.0.0/multi-dimensional-content-type-fields.png)
608+
![Multi-dimensional content type fields][11]
611609

612610
```markdown
613611
---
@@ -621,7 +619,7 @@ photo:
621619

622620
The `block` field type allows you to define a group of fields which can be used to create a list of data.
623621

624-
![Block field type rendering](/assets/block-field-type.png)
622+
![Block field type rendering][12]
625623

626624
### Prerequisites
627625

@@ -697,7 +695,7 @@ The `dataFile` field type allows you to use a data file to populate the field wi
697695
options. For instance, if you have a data file with all the authors of your site, you can use the
698696
`dataFile` field type to populate the `authors` field with the data from the authors data file.
699697

700-
![dataFile field](/releases/v7.3.0/datafile-field.png)
698+
![dataFile field][13]
701699

702700
### Prerequisites
703701

@@ -778,7 +776,7 @@ author:
778776

779777
The `slug` field allows you to create/update the slug of the current page.
780778

781-
![Slug field](/releases/v8.0.0/slug-field.png)
779+
![Slug field][14]
782780

783781
### Properties
784782

@@ -810,7 +808,7 @@ slug: version-8-0-0-release-notes
810808
```
811809

812810
> **Info**: The slug is generated based on the title of the page. More information about it can be
813-
> found in the [generate slug](/docs/commands#generate-slug-based-on-content-title) command section.
811+
> found in the [generate slug][15] command section.
814812

815813
## Divider
816814

@@ -832,7 +830,7 @@ You only need to specify the `type` property and name:
832830

833831
### Outcome
834832

835-
![Section divider field](/releases/v8.1.0/section-divider.png)
833+
![Section divider field][16]
836834

837835
## Heading
838836

@@ -857,4 +855,23 @@ want to group fields together.
857855

858856
### Outcome
859857

860-
![Section heading field](/releases/v8.1.0/section-heading.png)
858+
![Section heading field][17]
859+
860+
<!-- Link References -->
861+
[01]: /docs/content-creation/placeholders
862+
[02]: /docs/settings#frontmatter.global.disablednotifications
863+
[03]: /releases/v7.2.0/wysiwyg-controls.png
864+
[04]: https://date-fns.org/v2.0.1/docs/format
865+
[05]: /docs/settings#frontmatter.content.draftfield
866+
[06]: /releases/v5.3.0/draft-status.png
867+
[07]: /assets/tag-creation.png
868+
[08]: /assets/tags-limit.png
869+
[09]: /docs/content-creation/fields#tags
870+
[10]: /docs/content-creation/fields#block
871+
[11]: /releases/v6.0.0/multi-dimensional-content-type-fields.png
872+
[12]: /assets/block-field-type.png
873+
[13]: /releases/v7.3.0/datafile-field.png
874+
[14]: /releases/v8.0.0/slug-field.png
875+
[15]: /docs/commands#generate-slug-based-on-content-title
876+
[16]: /releases/v8.1.0/section-divider.png
877+
[17]: /releases/v8.1.0/section-heading.png

‎content/docs/content-creation/index.md

+4-1
Original file line numberDiff line numberDiff line change
@@ -57,4 +57,7 @@ Our default content type consists of the following fields:
5757
We'll use the default one when you start writing your markdown content, and no other content type is
5858
defined.
5959

60-
![Default content type fields](/assets/default-contenttype.png)
60+
![Default content type fields][01]
61+
62+
<!-- Link References -->
63+
[01]: /assets/default-contenttype.png

0 commit comments

Comments
 (0)