diff --git a/docs/userGuide/plugins/filterTags.mbdf b/docs/userGuide/plugins/filterTags.mbdf new file mode 100644 index 0000000000..ba70b592d5 --- /dev/null +++ b/docs/userGuide/plugins/filterTags.mbdf @@ -0,0 +1,155 @@ +#### `filterTags`: Toggling alternative contents in a page + +You can use tags to selectively filter HTML elements when building a site. + +Tags are specified by the `tags` attribute, **and can be attached to any HTML element**. During rendering, only elements that match tags specified in the `site.json` files will be rendered. + +
+ +{{ icon_example }} Attaching tags to elements: +```html +# Print 'Hello world' + +

System.out.println("Hello world");

+

Console.WriteLine("Hello world");

+

print("Hello world")

+``` + +You need to specify the tags to include in `site.json`, under the `tags` option: + +```json +{ + ... + "tags": ["language--java"] +} +``` + +All other tagged elements will be filtered out. In this case, only the element with the `language--java` tag will be rendered. This is helpful when creating multiple versions of a page without having to maintain separate copies. + +
+ +If the `tags` option is not specified in `site.json`, all tagged elements will be rendered. + +**You can also use multiple tags in a single HTML element. Specify each tag in the `tags` attribute** separated by a space. An element will be rendered if **any of the tags** matches the one in `site.json`. + +
+ +{{ icon_example }} Attaching multiple tags to an element: +```html +# For loops + +

for (int i = 0; i < 5; i++) { ... }

+``` + +As long as the `language--java` or `language--C#` tag is specified, the code snippet will be rendered. + +
+ +Alternatively, you can specify tags to render for a page in the front matter. + +
+ +{{ icon_example }} Specifying tags in front matter: +```html + + title: "Hello World" + tags: ["language--java"] + +``` +
+ + + +```html +

System.out.println("Hello world");

+

Console.WriteLine("Hello world");

+``` +```html + + title: "Hello World" + tags: ["language--java"] + +``` + + +Tags in `site.json` will be merged with the ones in the front matter, and are processed after front matter tags. See [Hiding Tags]({{ baseUrl }}/userGuide/tweakingThePageStructure.html#hiding-tags) for more information. + +#### Advanced Tagging Tips + +You can use a `*` in a tag name to match elements more generally. A `*` in a tag will match any number of characters at its position. + +
+ +{{ icon_example }} Using general tags: +```html + + title: "Hello World" + tags: ["language--*"] + + +

System.out.println("Hello world");

+

Console.WriteLine("Hello world");

+

print("Hello world")

+``` + +All 3 `

`s will be shown. + +

+ +#### Hiding Tags + +Using `-` at the start of a tag hides all tags matching the expression. This is helpful for disabling a group of tags and enabling a particular tag. + +
+ +{{ icon_example }} Using general tags: +```html +index.md + + + title: "Hello World" + tags: ["language--java"] + + +

System.out.println("Hello world");

+

Console.WriteLine("Hello world");

+

print("Hello world")

+``` + +```json +site.json + +{ + ... + "tags": ["-language--*", "language--C#"] +} +``` + +`language--java` is overridden by `-language--*`, so only `language--C#` is shown. + +
+ +This only works because tags are processed left to right, so all `language--*` tags are hidden before `language--C#`. Tags in `site.json` are processed after tags in ``. + + +```html +# Print 'Hello world' + +

System.out.println("Hello world");

+

Console.WriteLine("Hello world");

+

print("Hello world")

+``` +```json +{ + ... + "plugins" : [ + "filterTags" + ], + "pluginsContext" : { + "filterTags" : { + "tags": ["language--java"] + } + } +} +``` + diff --git a/docs/userGuide/syntax/tags.mbdf b/docs/userGuide/syntax/tags.mbdf index 2e639fab03..3f30c21a46 100644 --- a/docs/userGuide/syntax/tags.mbdf +++ b/docs/userGuide/syntax/tags.mbdf @@ -1,134 +1,5 @@ -## Tags - -You can use tags to selectively filter HTML elements when building a site. - -Tags are specified by the `tags` attribute, **and can be attached to any HTML element**. During rendering, only elements that match tags specified in the `site.json` files will be rendered. - -
- -{{ icon_example }} Attaching tags to elements: -```html -# Print 'Hello world' - -

System.out.println("Hello world");

-

Console.WriteLine("Hello world");

-

print("Hello world")

-``` - -You need to specify the tags to include in `site.json`, under the `tags` option: - -```json -{ - ... - "tags": ["language--java"] -} -``` - -All other tagged elements will be filtered out. In this case, only the element with the `language--java` tag will be rendered. This is helpful when creating multiple versions of a page without having to maintain separate copies. - -
- -If the `tags` option is not specified in `site.json`, all tagged elements will be rendered. - -**You can also use multiple tags in a single HTML element. Specify each tag in the `tags` attribute** separated by a space. An element will be rendered if **any of the tags** matches the one in `site.json`. - -
- -{{ icon_example }} Attaching multiple tags to an element: -```html -# For loops - -

for (int i = 0; i < 5; i++) { ... }

-``` - -As long as the `language--java` or `language--C#` tag is specified, the code snippet will be rendered. - -
- -Alternatively, you can specify tags to render for a page in the front matter. - -
- -{{ icon_example }} Specifying tags in front matter: -```html - - title: "Hello World" - tags: ["language--java"] - -``` -
+ - -```html -

System.out.println("Hello world");

-

Console.WriteLine("Hello world");

-``` -```html - - title: "Hello World" - tags: ["language--java"] - -``` + - -Tags in `site.json` will be merged with the ones in the front matter, and are processed after front matter tags. See [Hiding Tags]({{ baseUrl }}/userGuide/tweakingThePageStructure.html#hiding-tags) for more information. - -## Advanced Tagging Tips - -### General Tags - -You can use a `*` in a tag name to match elements more generally. A `*` in a tag will match any number of characters at its position. - -
- -{{ icon_example }} Using general tags: -```html - - title: "Hello World" - tags: ["language--*"] - - -

System.out.println("Hello world");

-

Console.WriteLine("Hello world");

-

print("Hello world")

-``` - -All 3 `

`s will be shown. - -

- -### Hiding Tags - -Using `-` at the start of a tag hides all tags matching the expression. This is helpful for disabling a group of tags and enabling a particular tag. - -
- -{{ icon_example }} Using general tags: -```html -index.md - - - title: "Hello World" - tags: ["language--java"] - - -

System.out.println("Hello world");

-

Console.WriteLine("Hello world");

-

print("Hello world")

-``` - -```json -site.json - -{ - ... - "tags": ["-language--*", "language--C#"] -} -``` - -`language--java` is overridden by `-language--*`, so only `language--C#` is shown. - -
- -This only works because tags are processed left to right, so all `language--*` tags are hidden before `language--C#`. Tags in `site.json` are processed after tags in ``. diff --git a/docs/userGuide/tweakingThePageStructure.md b/docs/userGuide/tweakingThePageStructure.md index e5e782a0ba..30a84d3a03 100644 --- a/docs/userGuide/tweakingThePageStructure.md +++ b/docs/userGuide/tweakingThePageStructure.md @@ -44,6 +44,6 @@
- + diff --git a/docs/userGuide/usingPlugins.md b/docs/userGuide/usingPlugins.md index dc57ef3c25..413fd18aaf 100644 --- a/docs/userGuide/usingPlugins.md +++ b/docs/userGuide/usingPlugins.md @@ -110,73 +110,6 @@ module.exports = { MarkBind has a set of built-in plugins that can be used immediately without installation. -#### `filterTags`: Toggling alternative contents in a page - -You can use tags to selectively filter HTML elements when building a site. - -Tags are specified by the `tags` attribute, **and can be attached to any HTML element**. During rendering, only elements that match tags specified in the `site.json` files will be rendered. - -
- -{{ icon_example }} Attaching tags to elements: -```html -# Print 'Hello world' - -

System.out.println("Hello world");

-

Console.WriteLine("Hello world");

-

print("Hello world")

-``` - -You need to specify the tags to include in the `pluginsContext`, under `tags`: - -```json -{ - ... - "plugins" : [ - "filterTags" - ], - "pluginsContext" : { - "filterTags" : { - "tags": ["language--java"] - } - } -} -``` - -All other tagged elements will be filtered out. In this case, only the element with the `language--java` tag will be rendered. This is helpful when creating multiple versions of a page without having to maintain separate copies. - -
- -If the `filterTags` plugin is not enabled in `site.json`, all tagged elements will be rendered. - -**You can also use multiple tags in a single HTML element. Specify each tag in the `tags` attribute** separated by a space. An element will be rendered if **any of the tags** matches the one in `site.json`. - -
- -{{ icon_example }} Attaching multiple tags to an element: -```html -# For loops - -

for (int i = 0; i < 5; i++) { ... }

-``` - -As long as the `language--java` or `language--C#` tag is specified, the code snippet will be rendered. - -
- -Alternatively, you can specify tags to render for a page in the front matter. - -
- -{{ icon_example }} Specifying tags in front matter: -```html - - title: "Hello World" - tags: ["language--java"] - -``` -
- -Tags in `site.json` will take precedence over the ones in the front matter. +