Skip to content

Fix tagging documentation #689

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
yamgent merged 1 commit into from
Feb 17, 2019
Merged

Fix tagging documentation #689

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
155 changes: 155 additions & 0 deletions docs/userGuide/plugins/filterTags.mbdf
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.

<div class="indented">

{{ icon_example }} Attaching tags to elements:
```html
# Print 'Hello world'

<p tags="language--java">System.out.println("Hello world");</p>
<p tags="language--C#">Console.WriteLine("Hello world");</p>
<p tags="language--python">print("Hello world")</p>
```

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.

</div>

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`.

<div class="indented">

{{ icon_example }} Attaching multiple tags to an element:
```html
# For loops

<p tags="language--java language--C#">for (int i = 0; i < 5; i++) { ... }</p>
```

As long as the `language--java` or `language--C#` tag is specified, the code snippet will be rendered.

</div>

Alternatively, you can specify tags to render for a page in the front matter.

<div class="indented">

{{ icon_example }} Specifying tags in front matter:
```html
<frontmatter>
title: "Hello World"
tags: ["language--java"]
</frontmatter>
```
</div>

<span id="short" class="d-none">

```html
<p tags="language--java advanced">System.out.println("Hello world");</p>
<p tags="language--C# basic">Console.WriteLine("Hello world");</p>
```
```html
<frontmatter>
title: "Hello World"
tags: ["language--java"]
</frontmatter>
```
</span>

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.

<div class="indented">

{{ icon_example }} Using general tags:
```html
<frontmatter>
title: "Hello World"
tags: ["language--*"]
</frontmatter>

<p tags="language--java">System.out.println("Hello world");</p>
<p tags="language--C#">Console.WriteLine("Hello world");</p>
<p tags="language--python">print("Hello world")</p>
```

All 3 `<p>`s will be shown.

</div>

#### 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.

<div class="indented">

{{ icon_example }} Using general tags:
```html
index.md

<frontmatter>
title: "Hello World"
tags: ["language--java"]
</frontmatter>

<p tags="language--java">System.out.println("Hello world");</p>
<p tags="language--C#">Console.WriteLine("Hello world");</p>
<p tags="language--python">print("Hello world")</p>
```

```json
site.json

{
...
"tags": ["-language--*", "language--C#"]
}
```

`language--java` is overridden by `-language--*`, so only `language--C#` is shown.

</div>

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 `<frontmatter>`.

<span id="short" class="d-none">
```html
# Print 'Hello world'

<p tags="language--java">System.out.println("Hello world");</p>
<p tags="language--C#">Console.WriteLine("Hello world");</p>
<p tags="language--python">print("Hello world")</p>
```
```json
{
...
"plugins" : [
"filterTags"
],
"pluginsContext" : {
"filterTags" : {
"tags": ["language--java"]
}
}
}
```
</span>
133 changes: 2 additions & 131 deletions docs/userGuide/syntax/tags.mbdf
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.

<div class="indented">

{{ icon_example }} Attaching tags to elements:
```html
# Print 'Hello world'

<p tags="language--java">System.out.println("Hello world");</p>
<p tags="language--C#">Console.WriteLine("Hello world");</p>
<p tags="language--python">print("Hello world")</p>
```

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.

</div>

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`.

<div class="indented">

{{ icon_example }} Attaching multiple tags to an element:
```html
# For loops

<p tags="language--java language--C#">for (int i = 0; i < 5; i++) { ... }</p>
```

As long as the `language--java` or `language--C#` tag is specified, the code snippet will be rendered.

</div>

Alternatively, you can specify tags to render for a page in the front matter.

<div class="indented">

{{ icon_example }} Specifying tags in front matter:
```html
<frontmatter>
title: "Hello World"
tags: ["language--java"]
</frontmatter>
```
</div>
<include src="../plugins/filterTags.mbdf" />

<span id="short" class="d-none">

```html
<p tags="language--java advanced">System.out.println("Hello world");</p>
<p tags="language--C# basic">Console.WriteLine("Hello world");</p>
```
```html
<frontmatter>
title: "Hello World"
tags: ["language--java"]
</frontmatter>
```
<include src="../plugins/filterTags.mbdf#short" />
Comment thread
Chng-Zhi-Xuan marked this conversation as resolved.
</span>

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.

<div class="indented">

{{ icon_example }} Using general tags:
```html
<frontmatter>
title: "Hello World"
tags: ["language--*"]
</frontmatter>

<p tags="language--java">System.out.println("Hello world");</p>
<p tags="language--C#">Console.WriteLine("Hello world");</p>
<p tags="language--python">print("Hello world")</p>
```

All 3 `<p>`s will be shown.

</div>

### 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.

<div class="indented">

{{ icon_example }} Using general tags:
```html
index.md

<frontmatter>
title: "Hello World"
tags: ["language--java"]
</frontmatter>

<p tags="language--java">System.out.println("Hello world");</p>
<p tags="language--C#">Console.WriteLine("Hello world");</p>
<p tags="language--python">print("Hello world")</p>
```

```json
site.json

{
...
"tags": ["-language--*", "language--C#"]
}
```

`language--java` is overridden by `-language--*`, so only `language--C#` is shown.

</div>

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 `<frontmatter>`.
2 changes: 1 addition & 1 deletion docs/userGuide/tweakingThePageStructure.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,6 @@

<hr><!-- ======================================================================================================= -->

<include src="syntax/tags.mbdf" />
<include src="plugins/filterTags.mbdf" />

</div>
69 changes: 1 addition & 68 deletions docs/userGuide/usingPlugins.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

<div class="indented">

{{ icon_example }} Attaching tags to elements:
```html
# Print 'Hello world'

<p tags="language--java">System.out.println("Hello world");</p>
<p tags="language--C#">Console.WriteLine("Hello world");</p>
<p tags="language--python">print("Hello world")</p>
```

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.

</div>

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`.

<div class="indented">

{{ icon_example }} Attaching multiple tags to an element:
```html
# For loops

<p tags="language--java language--C#">for (int i = 0; i < 5; i++) { ... }</p>
```

As long as the `language--java` or `language--C#` tag is specified, the code snippet will be rendered.

</div>

Alternatively, you can specify tags to render for a page in the front matter.

<div class="indented">

{{ icon_example }} Specifying tags in front matter:
```html
<frontmatter>
title: "Hello World"
tags: ["language--java"]
</frontmatter>
```
</div>

Tags in `site.json` will take precedence over the ones in the front matter.
<include src="plugins/filterTags.mbdf" />

</div>