Skip to content

Add documentation that markdown is not rendered when including variables #2258

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

Closed
yucheng11122017 wants to merge 2 commits into from
Closed

Add documentation that markdown is not rendered when including variables #2258

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
70a9725
Add documentation that markdown is not rendered when including variables
yucheng11122017 Apr 2, 2023
830efa0
Merge branch 'master' of https://github.com/MarkBind/markbind into ad…
yucheng11122017 Apr 2, 2023
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
56 changes: 56 additions & 0 deletions docs/userGuide/syntax/includes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,62 @@ The `<include>` mechanism can be used inside any MarkBind source file (even insi
</span>
</include>

<panel header="Markdown not rendered when including a variable">

@damithc damithc Apr 2, 2023

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The heading should let the reader decide quickly between expanding and reading the panel or skipping it. This one is hard to decide (is this a tip, advanced technique, caveat, etc.?), and the reader will have to expand the panel to figure out what it's about.

@yucheng11122017 yucheng11122017 Apr 2, 2023

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmmm how about "If trying to include a variable with markdown" or something like that?


When trying to include a variable, markdown is not rendered.

To fix this, either replace the markdown with html tags if possible or replace the `include` with the fragment.

{{ icon_example }}

<box>

Include fragment in file "index.md":
```html
<variable id="fragment-id">

### I am a header
</variable>
```

Code that uses include fragment:
```html
<include src="index.md#fragment-id" />
```

@damithc damithc Apr 2, 2023

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Something is not right here. I don't think variables are meant to be used as include fragments in the first place. Although it would be nice 'trick' to be able to do so, I don't think it is an advertised feature. Variable values are inserted using the {{ v_name }} instead. Does our UG say variables can be included in this way?

image

@yucheng11122017 yucheng11122017 Apr 2, 2023

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh I see I see. In that case, I will close this PR and the corresponding issue :)


The markdown will not render correctly and instead will appear as text '### I am a header'.
</box>

To fix this, either replace the markdown with html tags if possible or replace the `include` with the fragment.

{{ icon_example }} Replacing markdown with html tags:

<box>

Include fragment in file "index.md":
```html
<variable id="fragment-id">
<h3>I am a header<h3>
</variable>
```

Code that uses include fragment:
```html
<include src="index.md#fragment-id" />
```
</box>

{{ icon_example }} Replacing the `include` with the fragment:

<box>
Code that is supposed to use include fragment:

```html
### I am a header
```
</box>
</panel>

**Attributes:**
* **`src`**: specify the source file path.
* **`inline`** (optional): make the included result an inline element. (wrapped in `<span>` tag). e.g.,
Expand Down