Skip to content

Commit

Permalink
Support Relative References: Update User Guide
Browse files Browse the repository at this point in the history
Our user guide does not mention how users should use relative URL
references. Now that parser fully supports relative URL references
for images and links, let's update our user guide to document
MarkBind's behavior towards relative references.

In particular, the intra-site links section has been updated with
an important note on how users should specify relative references,
while images and pictures section have been updated with a note
teaching users that they can now use relative references.
  • Loading branch information
sijie123 committed Apr 16, 2019
1 parent 76a8572 commit 8890044
Show file tree
Hide file tree
Showing 3 changed files with 12 additions and 4 deletions.
4 changes: 4 additions & 0 deletions docs/userGuide/syntax/images.mbdf
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,10 @@
```markdown
![](https://markbind.org/images/logo-lightbackground.png)
```
<box type="info">
URLs can be specified as relative references. More info in: <i><a href="#intraSiteLinks">Intra-Site Links</a></i>
</box>

</span>
<span id="output">

Expand Down
10 changes: 7 additions & 3 deletions docs/userGuide/syntax/links.mbdf
Original file line number Diff line number Diff line change
Expand Up @@ -56,12 +56,14 @@ Links should start with {{ showBaseUrlCode }} (which represents the root directo
1. <code>Click [here]({{ showBaseUrlCode }}/userGuide/reusingContents.html).</code>
2. `![](`{{ showBaseUrlCode }}`/images/preview.png)`

<box type="important">
To ensure that links in the <code>_markbind/</code> folder work correctly across the entire site, they should be written as absolute paths, prepended with <code><span>{</span>{ baseUrl }}</code>.
</box>
</div>

Relative paths:

<div class="indented">
Links to files can also be specified relative to the file that includes it.

{{ icon_example }} Assuming that we have the following folder structure:
```
Expand All @@ -83,12 +85,14 @@ Within `index.md`, we can also display the image using
<img src="textbook/image.png" />
```
or by including `subsite.md`:
```
```html
<include src="textbook/subsite.md" />
```

<box type="important">
To ensure that links in the _markbind/ folder work correctly across the entire site, they should be written as absolute paths, prepended with <span>{</span>{ baseUrl }}.
Relative links to resources (e.g. images, hrefs) should be valid relative to the original, included file. In other words, the links should be accessible when traversing starting from the location of the included file.
<br>
In the example above, <code>image.png</code> is in the same directory as <code>subsite.md</code>. When using relative references, the correct path is <code>image.png</code> and not <code>textbook/image.png</code>.
</box>

</div>
Expand Down
2 changes: 1 addition & 1 deletion docs/userGuide/syntax/pictures.mbdf
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ Name | Type | Default | Description
--- | --- | --- | ---
alt | `string` | | **This must be specified.**<br>The alternative text of the image.
height | `string` | | The height of the image in pixels.
src | `string` | | **This must be specified.**<br>The URL of the image.
src | `string` | | **This must be specified.**<br>The URL of the image.<br>The URL can be specified as absolute or relative references. More info in: _[Intra-Site Links]({{baseUrl}}/userGuide/formattingContents.html#intraSiteLinks)_
width | `string` | | The width of the image in pixels.<br>If both width and height are specified, width takes priority over height. It is to maintain the image's aspect ratio.

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

0 comments on commit 8890044

Please sign in to comment.