From 111720855d54dee0b6e54e74a13ef15bb6e090e4 Mon Sep 17 00:00:00 2001 From: Si Jie Date: Thu, 7 Feb 2019 14:38:31 +0700 Subject: [PATCH 1/2] Convert relative src references to absolute paths When including files from a sub-site or a sub-folder within the same site, Markbind only automatically resolves src references for the include and panel tags. This means that references to any other resources (such as anchor#href, img#src and pic#src) do not get resolved and converted. When these markdown files containing relative resource references are included by another file in a different directory, the links remain unchanged. From the perspective of the outer document, the references become broken and files become not found. To resolve this problem, let's convert all relative resource references to absolute ones. This allows the references to work consistently across all instances of reuse. This conversion process adds on to the existing preprocess step and is similar to how we currently resolve src references in include and panel tags. --- src/lib/markbind/src/parser.js | 31 ++++++++++++++++--- test/functional/test_site/expected/index.html | 21 +++++++++++++ .../sub_site/testReuse._include_.html | 18 +++++++++++ test/functional/test_site/index.md | 3 ++ .../test_site/sub_site/testReuse.md | 23 ++++++++++++++ 5 files changed, 92 insertions(+), 4 deletions(-) create mode 100644 test/functional/test_site/expected/sub_site/testReuse._include_.html create mode 100644 test/functional/test_site/sub_site/testReuse.md diff --git a/src/lib/markbind/src/parser.js b/src/lib/markbind/src/parser.js index 8f5d722e37..aca78eaa67 100644 --- a/src/lib/markbind/src/parser.js +++ b/src/lib/markbind/src/parser.js @@ -172,21 +172,22 @@ Parser.prototype._preprocess = function (node, context, config) { element.attribs = element.attribs || {}; element.attribs[ATTRIB_CWF] = path.resolve(context.cwf); - const requiresSrc = ['include'].includes(element.name); + const requiresSrc = ['img', 'pic', 'include'].includes(element.name); if (requiresSrc && _.isEmpty(element.attribs.src)) { const error = new Error(`Empty src attribute in ${element.name} in: ${element.attribs[ATTRIB_CWF]}`); this._onError(error); return createErrorNode(element, error); } - - const shouldProcessSrc = ['include', 'panel'].includes(element.name); + const shouldProcessSrc = ['img', 'pic', 'include', 'panel'].includes(element.name); const hasSrc = _.hasIn(element.attribs, 'src'); let isUrl; let includeSrc; let filePath; + let isAbsolutePath; let actualFilePath; if (hasSrc && shouldProcessSrc) { isUrl = utils.isUrl(element.attribs.src); + isAbsolutePath = path.isAbsolute(element.attribs.src) || element.attribs.src.includes('{{baseUrl}}'); includeSrc = url.parse(element.attribs.src); filePath = isUrl ? element.attribs.src @@ -199,7 +200,7 @@ Parser.prototype._preprocess = function (node, context, config) { this.boilerplateIncludeSrc.push({ from: context.cwf, to: actualFilePath }); } const isOptional = element.name === 'include' && _.hasIn(element.attribs, 'optional'); - if (!utils.fileExists(actualFilePath)) { + if (!['img', 'pic'].includes(element.name) && !utils.fileExists(actualFilePath)) { if (isOptional) { return createEmptyNode(); } @@ -212,6 +213,18 @@ Parser.prototype._preprocess = function (node, context, config) { } } + const shouldProcessHref = ['a', 'link'].includes(element.name); + const hasHref = _.hasIn(element.attribs, 'href'); + if (hasHref && shouldProcessHref) { + isUrl = utils.isUrl(element.attribs.href); + isAbsolutePath = path.isAbsolute(element.attribs.href) || element.attribs.href.startsWith('{{'); + includeSrc = url.parse(element.attribs.href); + filePath = isUrl + ? element.attribs.src + : path.resolve(path.dirname(context.cwf), decodeURIComponent(includeSrc.path)); + actualFilePath = filePath; + } + if (element.name === 'include') { const isInline = _.hasIn(element.attribs, 'inline'); const isDynamic = _.hasIn(element.attribs, 'dynamic'); @@ -370,6 +383,16 @@ Parser.prototype._preprocess = function (node, context, config) { if (element.name === 'body') { // eslint-disable-next-line no-console console.warn(` tag found in ${element.attribs[ATTRIB_CWF]}. This may cause formatting errors.`); + } else if (['img', 'pic'].includes(element.name)) { + if (!isUrl && !isAbsolutePath) { + const resultPath = path.join('{{hostBaseUrl}}', path.relative(config.rootPath, filePath)); + element.attribs.src = utils.ensurePosix(resultPath); + } + } else if (['a', 'link'].includes(element.name)) { + if (!isUrl && !isAbsolutePath) { + const resultPath = path.join('{{hostBaseUrl}}', path.relative(config.rootPath, filePath)); + element.attribs.href = utils.ensurePosix(resultPath); + } } if (element.children && element.children.length > 0) { element.children = element.children.map(e => self._preprocess(e, context, config)); diff --git a/test/functional/test_site/expected/index.html b/test/functional/test_site/expected/index.html index 023ef19a75..a054bacb13 100644 --- a/test/functional/test_site/expected/index.html +++ b/test/functional/test_site/expected/index.html @@ -453,6 +453,26 @@

Feature list<
  • Timer – Additional fixed time restriction on the player.
    • +
    +

    This is a page from another Markbind site. The purpose of this page is to ensure that reuse works as expected. All the following images should display correctly.

    +

    Some variables:

    +
    +

    IMG tags: + + + + +

    +

    PIC tags: + + + + + +

    +

    Anchor link: + External Image

    +

    Trimmed include

    Fragment with leading spaces and newline

    Include with custom variables

    @@ -514,6 +534,7 @@

    Panel content of inner nested panel

    Panel with src from another Markbind site

    +

    Modal with panel inside

    diff --git a/test/functional/test_site/expected/sub_site/testReuse._include_.html b/test/functional/test_site/expected/sub_site/testReuse._include_.html new file mode 100644 index 0000000000..afbeab0ff9 --- /dev/null +++ b/test/functional/test_site/expected/sub_site/testReuse._include_.html @@ -0,0 +1,18 @@ +

    This is a page from another Markbind site. The purpose of this page is to ensure that reuse works as expected. All the following images should display correctly.

    +

    Some variables:

    +
    +

    IMG tags: + + + + +

    +

    PIC tags: + + + + + +

    +

    Anchor link: + External Image

    \ No newline at end of file diff --git a/test/functional/test_site/index.md b/test/functional/test_site/index.md index e727af6f8f..848ab7d2e1 100644 --- a/test/functional/test_site/index.md +++ b/test/functional/test_site/index.md @@ -127,6 +127,7 @@ tags: ["tag-frontmatter-shown", "tag-included-file", "+tag-exp*", "-tag-exp-hidd # Include from another Markbind site + # Trimmed include @@ -189,6 +190,8 @@ tags: ["tag-frontmatter-shown", "tag-included-file", "+tag-exp*", "-tag-exp-hidd # Panel with src from another Markbind site + + # Modal with panel inside diff --git a/test/functional/test_site/sub_site/testReuse.md b/test/functional/test_site/sub_site/testReuse.md new file mode 100644 index 0000000000..33eb0dbabb --- /dev/null +++ b/test/functional/test_site/sub_site/testReuse.md @@ -0,0 +1,23 @@ +This is a page from another Markbind site. +The purpose of this page is to ensure that reuse works as expected. +All the following images should display correctly. + +Some variables: +images + +IMG tags: + + + + + + +PIC tags: + + + + + + +Anchor link: +External Image \ No newline at end of file From 8482de033b8bcbc4926f32c6bd40400d5ed505a0 Mon Sep 17 00:00:00 2001 From: Si Jie Date: Sat, 2 Mar 2019 20:58:56 +0700 Subject: [PATCH 2/2] Documentation: Remove unnecessary {{baseUrl}} The documentation uses {{baseUrl}} to create absolute references to many resources, including CSS files, links and images. This was necessary because we did not have features to support dynamic resource references. To ensure that our sites render consistently regardless of the page that the user is in, we manually referenced each resource with respect to an absolute {{baseUrl}}. This is no longer necessary, as we can now support relative paths. As Markbind can now automatically convert relative resource references to absolute ones, we can remove {{baseUrl}} to make it easier to maintain the documentation in the future. In this commit, all unnecessary references to {{baseUrl}} have been removed, except for mbdf files within userGuide/syntax and userGuide/plugins. These files are meant as the central reference within the user guide, and removing {{baseUrl}} from these files might make it confusing to maintain or add new documentation in the future. --- docs/_markbind/variables.md | 2 +- docs/common/header.md | 12 +++---- docs/index.md | 18 +++++----- docs/userGuide/addingPages.md | 6 ++-- docs/userGuide/cliCommands.md | 2 +- docs/userGuide/deployingTheSite.md | 8 ++--- docs/userGuide/formattingContents.md | 2 +- docs/userGuide/gettingStarted.md | 4 +-- docs/userGuide/glossary.md | 2 +- docs/userGuide/makingTheSiteSearchable.md | 6 ++-- .../userGuide/markBindInTheProjectWorkflow.md | 4 +-- docs/userGuide/markBindSyntaxOverview.md | 2 +- docs/userGuide/plugins/filterTags.mbdf | 2 +- docs/userGuide/reusingContents.md | 12 +++---- docs/userGuide/siteConfiguration.md | 6 ++-- docs/userGuide/syntax/links.mbdf | 36 +++++++++++++++++-- docs/userGuide/tweakingThePageStructure.md | 2 +- docs/userGuide/usingComponents.md | 2 +- docs/userGuide/usingHtmlJavaScriptCss.md | 2 +- 19 files changed, 81 insertions(+), 49 deletions(-) diff --git a/docs/_markbind/variables.md b/docs/_markbind/variables.md index 9facd789e3..5017ca8573 100644 --- a/docs/_markbind/variables.md +++ b/docs/_markbind/variables.md @@ -16,7 +16,7 @@ :fas-info-circle: :far-check-square: -[live preview]({{ baseUrl }}/userGuide/glossary.html#live-preview) +[live preview](userGuide/glossary.html#live-preview) root directory diff --git a/docs/common/header.md b/docs/common/header.md index 625c2202f8..5b6107cc36 100644 --- a/docs/common/header.md +++ b/docs/common/header.md @@ -1,10 +1,10 @@ - + - -
  • HOME
    • -
  • DOCS
    • -
  • SHOWCASE
    • -
  • ABOUT
    • + +
  • HOME
    • +
  • DOCS
    • +
  • SHOWCASE
    • +
  • ABOUT
  • diff --git a/docs/index.md b/docs/index.md index 9370d21e70..5a3dd50de6 100644 --- a/docs/index.md +++ b/docs/index.md @@ -13,13 +13,13 @@ Optimized for creating text-heavy websites %%e.g., eLearning websites, online instruction manuals, project documentation etc.%%. -Get Started +Get Started
    #### {{ icon_check_blue }} Simple syntax. Dynamic content. -MarkBind source files can be as simple as basic Markdown, but you can also [**use a mix of several popular syntax schemes**]({{ baseUrl }}/userGuide/markBindSyntax.html) (GFMD, BootStrap, NunJucks, etc. as well as MarkBind's own custom syntax) to create more dynamic content that you cannot normally get from a typical markdown-to-html site generator. +MarkBind source files can be as simple as basic Markdown, but you can also [**use a mix of several popular syntax schemes**](userGuide/markBindSyntax.html) (GFMD, BootStrap, NunJucks, etc. as well as MarkBind's own custom syntax) to create more dynamic content that you cannot normally get from a typical markdown-to-html site generator. Here are some simple text-formatting examples: @@ -131,16 +131,16 @@ MarkBind is **highly optimized for creating text-heavy websites** %%e.g., eLearn Here are some examples:
    -:fas-heart: **Icons** can improve the readability of a text-heavy document. MarkBind comes with a wide selection of [icons]({{ baseUrl }}/userGuide/markBindSyntax.html#icons-fonts) and [emoji]({{ baseUrl }}/userGuide/markBindSyntax.html#emoji).
    -:fas-search: With MarkBind's [**search feature**]({{ baseUrl }}/userGuide/makingTheSiteSearchable.html), you can allow readers to search for keywords in your site.
    -:fas-window-maximize: MarkBind allows you to add [**site/page navigation menus, headers, footers**]({{ baseUrl }}/userGuide/tweakingThePageStructure.html) easily. +:fas-heart: **Icons** can improve the readability of a text-heavy document. MarkBind comes with a wide selection of [icons](userGuide/markBindSyntax.html#icons-fonts) and [emoji](userGuide/markBindSyntax.html#emoji).
    +:fas-search: With MarkBind's [**search feature**](userGuide/makingTheSiteSearchable.html), you can allow readers to search for keywords in your site.
    +:fas-window-maximize: MarkBind allows you to add [**site/page navigation menus, headers, footers**](userGuide/tweakingThePageStructure.html) easily.
    #### {{ icon_check_blue }} More control to the reader, without duplicating code. -A MarkBind website can be a _buffet_ of content, as opposed to a _set menu_: a site can have optional contents that the reader can access at her discretion, and the same content can be organized in multiple ways so that the reader can choose the one that fits the need. To _cater_ (pun intended) for creating such buffet style websites, MarkBind has **[reuse mechanisms]({{ baseUrl }}/userGuide/reusingContents.html) for presenting the same content in multiple ways without duplicating the source file**. +A MarkBind website can be a _buffet_ of content, as opposed to a _set menu_: a site can have optional contents that the reader can access at her discretion, and the same content can be organized in multiple ways so that the reader can choose the one that fits the need. To _cater_ (pun intended) for creating such buffet style websites, MarkBind has **[reuse mechanisms](userGuide/reusingContents.html) for presenting the same content in multiple ways without duplicating the source file**. For example, MarkBind has a powerful `include` mechanism that allows content fragments (i.e., a file or part of a file) to be reused at multiple places in the website. In the example below, both the modal and the expandable panel reuse the same content originating from a _single_ source file. @@ -162,8 +162,8 @@ In CS, a binary tree is a tree data structure in which each node has at most two #### {{ icon_check_blue }} Easy to set up, modify, deploy, integrate. -Installing MarkBind takes just one command. Creating a new MarkBind site too takes just one command. With MarkBind's _live preview_ feature, you can see how your site will look like as you modify the source file. [Deploying the site to a server]({{ baseUrl }}/userGuide/deployingTheSite.html) can be as simple as one command too. +Installing MarkBind takes just one command. Creating a new MarkBind site too takes just one command. With MarkBind's _live preview_ feature, you can see how your site will look like as you modify the source file. [Deploying the site to a server](userGuide/deployingTheSite.html) can be as simple as one command too. -As MarkBind is also optimized for project documentation, it can easily [integrate with the workflow of a software project]({{ baseUrl }}/userGuide/markBindInTheProjectWorkflow.html). +As MarkBind is also optimized for project documentation, it can easily [integrate with the workflow of a software project](userGuide/markBindInTheProjectWorkflow.html). -Get Started +Get Started diff --git a/docs/userGuide/addingPages.md b/docs/userGuide/addingPages.md index 1cdebc7d07..662c62bb0d 100644 --- a/docs/userGuide/addingPages.md +++ b/docs/userGuide/addingPages.md @@ -8,7 +8,7 @@ -[_User Guide → {{ title }}_]({{ baseUrl }}/userGuide/{{ filename }}.html) +[_User Guide → {{ title }}_]({{ filename }}.html) @@ -28,7 +28,7 @@ -%%You can specify which files to be omitted from the site by using the `ignore` field in the `site.config` file as explained [here]({{ baseUrl }}/userGuide/siteConfiguration.html#ignore).%% +%%You can specify which files to be omitted from the site by using the `ignore` field in the `site.config` file as explained [here](siteConfiguration.html#ignore).%% **More importantly, `.md` and `.mbd` files can be transformed into html pages with matching names.** @@ -40,7 +40,7 @@ Here are the steps to add a new page to your site: 1. Add a `.md` (or `.mbd`) file anywhere inside the root directory. -1. Update the [`pages` attribute of the `site.json`]({{ baseUrl }}/userGuide/siteConfiguration.html#pages) to cover the new file, if necessary. +1. Update the [`pages` attribute of the `site.json`](siteConfiguration.html#pages) to cover the new file, if necessary. 1. Use the live preview to view the generated web page for the new file. diff --git a/docs/userGuide/cliCommands.md b/docs/userGuide/cliCommands.md index 0cd914a4c4..e7647809ff 100644 --- a/docs/userGuide/cliCommands.md +++ b/docs/userGuide/cliCommands.md @@ -62,7 +62,7 @@ MarkBind Command Line Interface (CLI) can be run in the following ways: Deploy the site in Travis CI using the GitHub personal access token stored in ``. (default: `GITHUB_TOKEN`)
    {{ icon_example }} `-t PA_TOKEN` -%%{{ icon_info }} Related: [User Guide: Deploying the Website]({{ baseUrl }}/userGuide/deployingTheSite.html).%% +%%{{ icon_info }} Related: [User Guide: Deploying the Website](deployingTheSite.html).%%
    diff --git a/docs/userGuide/deployingTheSite.md b/docs/userGuide/deployingTheSite.md index e1cd359e4b..39ad80a224 100644 --- a/docs/userGuide/deployingTheSite.md +++ b/docs/userGuide/deployingTheSite.md @@ -16,9 +16,9 @@ Generic steps for deploying a MarkBind site: -1. Set the [`baseUrl` property of the `site.json` file]({{ baseUrl }}/userGuide/siteConfiguration.html#baseUrl) to match the deploy location. -1. (Optional) Use the [`markbind serve` command]({{ baseUrl }}/userGuide/cliCommands.html#serve-command) to stage the site locally and confirm the contents are as expected. -1. Use the [`markbind build` command]({{ baseUrl }}/userGuide/cliCommands.html#build-command) to generate the site from source files. That command puts the generated site files in a directory named `_site` (you can change the output directory using parameters supplied to the command). +1. Set the [`baseUrl` property of the `site.json` file](siteConfiguration.html#baseUrl) to match the deploy location. +1. (Optional) Use the [`markbind serve` command](cliCommands.html#serve-command) to stage the site locally and confirm the contents are as expected. +1. Use the [`markbind build` command](cliCommands.html#build-command) to generate the site from source files. That command puts the generated site files in a directory named `_site` (you can change the output directory using parameters supplied to the command). 1. Upload the site files to the Web server. The sections below explains how to automate this step for when deploying to some online platforms. ## Deploying to Github Pages @@ -39,7 +39,7 @@ If you are deploying to the site to GitHub pages, the `baseUrl` setting in the ` You can override the default deployment settings %%(e.g., repo/branch to deploy)%% in the `site.json`'s `deploy` section: - + diff --git a/docs/userGuide/formattingContents.md b/docs/userGuide/formattingContents.md index 8778f013cd..09d506264b 100644 --- a/docs/userGuide/formattingContents.md +++ b/docs/userGuide/formattingContents.md @@ -9,7 +9,7 @@ -[_User Guide → {{ title }}_]({{ baseUrl }}/userGuide/{{ filename }}.html) +[_User Guide → {{ title }}_]({{ filename }}.html) diff --git a/docs/userGuide/gettingStarted.md b/docs/userGuide/gettingStarted.md index e1a4ca96f5..0fc5076f3c 100644 --- a/docs/userGuide/gettingStarted.md +++ b/docs/userGuide/gettingStarted.md @@ -85,8 +85,8 @@ To stop the web server, go to the console running the `serve` command and press **4. Next steps** -1. **Update the content of your site**. More info can be found in the [_User Guide: Authoring Contents_]({{ baseUrl }}/userGuide/authoringContents.html) section -1. **Deploy your site**. More info can be found in the [_User Guide: Deploying the Site_]({{ baseUrl }}/userGuide/deployingTheSite.html) section. +1. **Update the content of your site**. More info can be found in the [_User Guide: Authoring Contents_](authoringContents.html) section +1. **Deploy your site**. More info can be found in the [_User Guide: Deploying the Site_](deployingTheSite.html) section. {% from "njk/common.njk" import previous_next %} {{ previous_next('', 'authoringContents') }} diff --git a/docs/userGuide/glossary.md b/docs/userGuide/glossary.md index adae15455c..519ad72cdd 100644 --- a/docs/userGuide/glossary.md +++ b/docs/userGuide/glossary.md @@ -13,7 +13,7 @@ {{ icon_info }} Live preview works for the following file types only: `css`, `.html`, `.md`, `.mbd`, `.mbdf`. Changes to `css` might may not be visible in the site until you do a manual refresh of the page. -Use [the `serve` command]({{ baseUrl }}/userGuide/cliCommands.html#serve-command) to launch a live preview. +Use [the `serve` command](cliCommands.html#serve-command) to launch a live preview. diff --git a/docs/userGuide/makingTheSiteSearchable.md b/docs/userGuide/makingTheSiteSearchable.md index e7ed75591b..5e890ea9b5 100644 --- a/docs/userGuide/makingTheSiteSearchable.md +++ b/docs/userGuide/makingTheSiteSearchable.md @@ -9,7 +9,7 @@ -[_User Guide → {{ title }}_]({{ baseUrl }}/userGuide/{{ filename }}.html) +[_User Guide → {{ title }}_]({{ filename }}.html) @@ -18,10 +18,10 @@ -**MarkBind comes with with an in-built _site search_ facility**. You can add a [Search Bar]({{ baseUrl }}/userGuide/usingComponents.html#search-bar) component to your pages %%(e.g., into the top navigation bar)%% to allow readers to search your website for keywords. +**MarkBind comes with with an in-built _site search_ facility**. You can add a [Search Bar](usingComponents.html#search-bar) component to your pages %%(e.g., into the top navigation bar)%% to allow readers to search your website for keywords. -**All headings of levels 1-3 are captured in the search index** by default. You can change this setting using the [`headingIndexLevel` property of the `site.json`]({{ baseUrl }}/userGuide/siteConfiguration.html#headingindexinglevel). +**All headings of levels 1-3 are captured in the search index** by default. You can change this setting using the [`headingIndexLevel` property of the `site.json`](siteConfiguration.html#headingindexinglevel). diff --git a/docs/userGuide/markBindInTheProjectWorkflow.md b/docs/userGuide/markBindInTheProjectWorkflow.md index 0e79869605..1e0c33efd8 100644 --- a/docs/userGuide/markBindInTheProjectWorkflow.md +++ b/docs/userGuide/markBindInTheProjectWorkflow.md @@ -20,9 +20,9 @@ While most IDEs provide previews for Markdown files, unless your MarkBind files #### GitHub Project Workflow -If you use GitHub for your project, you can [deploy your site to GitHub pages]({{ baseUrl }}/userGuide/deployingTheSite.html#deploying-to-github-pages) easily. You can even set up Travis to automatically deploy your site to GitHub pages whenever a branch in your repo is updated. +If you use GitHub for your project, you can [deploy your site to GitHub pages](deployingTheSite.html#deploying-to-github-pages) easily. You can even set up Travis to automatically deploy your site to GitHub pages whenever a branch in your repo is updated. -If you are using GitHub Pull Requests as part of your workflow, you can [set up Netlify to show a preview of the site generated from the MarkBind code in the PR]({{ baseUrl }}/userGuide/deployingTheSite.html#deploying-to-netlify). +If you are using GitHub Pull Requests as part of your workflow, you can [set up Netlify to show a preview of the site generated from the MarkBind code in the PR](deployingTheSite.html#deploying-to-netlify). #### Using MarkBind for Project Documentation diff --git a/docs/userGuide/markBindSyntaxOverview.md b/docs/userGuide/markBindSyntaxOverview.md index 6e4cb0f5d3..7a70203bbe 100644 --- a/docs/userGuide/markBindSyntaxOverview.md +++ b/docs/userGuide/markBindSyntaxOverview.md @@ -8,7 +8,7 @@ -[_User Guide → {{ title }}_]({{ baseUrl }}/userGuide/{{ filename }}.html) +[_User Guide → {{ title }}_]({{ filename }}.html) diff --git a/docs/userGuide/plugins/filterTags.mbdf b/docs/userGuide/plugins/filterTags.mbdf index ba70b592d5..15ba1f1eb4 100644 --- a/docs/userGuide/plugins/filterTags.mbdf +++ b/docs/userGuide/plugins/filterTags.mbdf @@ -72,7 +72,7 @@ Alternatively, you can specify tags to render for a page in the front matter. ``` -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. +Tags in `site.json` will be merged with the ones in the front matter, and are processed after front matter tags. See [Hiding Tags](userGuide/tweakingThePageStructure.html#hiding-tags) for more information. #### Advanced Tagging Tips diff --git a/docs/userGuide/reusingContents.md b/docs/userGuide/reusingContents.md index d30e3940c5..b6832346e8 100644 --- a/docs/userGuide/reusingContents.md +++ b/docs/userGuide/reusingContents.md @@ -9,7 +9,7 @@ -[_User Guide → {{ title }}_]({{ baseUrl }}/userGuide/{{ filename }}.html) +[_User Guide → {{ title }}_]({{ filename }}.html) @@ -100,17 +100,17 @@ Optional video: #### Giving alternative contents -You can use a [_Tabs_ component]({{ baseUrl }}/userGuide/usingComponents.html#tabs) to give alternative versions of content, for example, giving a code snippet in different programming languages. +You can use a [_Tabs_ component](usingComponents.html#tabs) to give alternative versions of content, for example, giving a code snippet in different programming languages. #### Giving access to additional contents You can use following components to give readers an option to access additional content at their discretion. -* [Tooltips]({{ baseUrl }}/userGuide/usingComponents.html#tooltip), [Popovers]({{ baseUrl }}/userGuide/usingComponents.html#popover), [Modals]({{ baseUrl }}/userGuide/usingComponents.html#modal) -* [Expandable Panels]({{ baseUrl }}/userGuide/usingComponents.html#panel) +* [Tooltips](usingComponents.html#tooltip), [Popovers](usingComponents.html#popover), [Modals](usingComponents.html#modal) +* [Expandable Panels](usingComponents.html#panel) #### Organizing contents in alternative ways -You can take advantage of [MarkBinds feature for content reuse]({{ baseUrl }}/userGuide/reusingContents.html), you can organize content in alternative ways to cater for different readers, without having to duplicate content. For example, you can have different pages that organizes the same information alphabetically, chronologically, by difficulty, group information by topic, etc. +You can take advantage of [MarkBinds feature for content reuse](reusingContents.html), you can organize content in alternative ways to cater for different readers, without having to duplicate content. For example, you can have different pages that organizes the same information alphabetically, chronologically, by difficulty, group information by topic, etc. #### Optimizing the Print View @@ -154,7 +154,7 @@ Then, in a page-specific CSS file, #### Creating slight variations of content -Tags are a good way to create multiple variations of a page within the same source file, such as to filter content for creating multiple different versions of the same page. See [_User Guide: Tweaking the Page Structure → Tags_]({{ baseUrl }}/userGuide/tweakingThePageStructure.html#tags) section for more information. +Tags are a good way to create multiple variations of a page within the same source file, such as to filter content for creating multiple different versions of the same page. See [_User Guide: Tweaking the Page Structure → Tags_](tweakingThePageStructure.html#tags) section for more information. {% from "njk/common.njk" import previous_next %} {{ previous_next('tweakingThePageStructure', 'makingTheSiteSearchable') }} diff --git a/docs/userGuide/siteConfiguration.md b/docs/userGuide/siteConfiguration.md index 41860d0bbf..b4a4860c25 100644 --- a/docs/userGuide/siteConfiguration.md +++ b/docs/userGuide/siteConfiguration.md @@ -85,7 +85,7 @@ Here is a typical `site.json` file: * **`src`**/**`glob`**: `src` can be used to specify a file e.g., `docs/index.md`.
    Alternatively, `glob` can be used to define a file pattern in the [_glob syntax_](https://en.wikipedia.org/wiki/Glob_(programming)) e.g., `**/*.md`. * **`title`**: The page `` for the generated web page. Titles specified here take priority over titles specified in the [front matter](addingPages.html#front-matter) of individual pages. -* **`layout`**: The [layout]({{ baseUrl }}/userGuide/tweakingThePageStructure.html#page-layouts) to be used by the page. Default: `default`. +* **`layout`**: The [layout](tweakingThePageStructure.html#page-layouts) to be used by the page. Default: `default`. * **`searchable`**: Specifies that the page(s) should be excluded from searching. Default: `yes`. * **`externalScripts`**: An array of external scripts to be referenced on the page. Scripts referenced will be run before the layout script. @@ -150,7 +150,7 @@ The ignore pattern follows the [glob pattern used in .gitignore](https://git-scm #### **`deploy`** -**The settings for [auto-deployment to Github pages]({{ baseUrl }}/userGuide/deployingTheSite.html).** +**The settings for [auto-deployment to Github pages](deployingTheSite.html).** * **`message`** [Optional. Default: `"Site Update."`]<br> The commit message used for the deployment commit. @@ -174,4 +174,4 @@ The ignore pattern follows the [glob pattern used in .gitignore](https://git-scm #### **`enableSearch`** -**Specifies that the website should use MarkBind's search functionality.** Default: `true`. See [User Guide: Making the Site Searchable]({{ baseUrl }}/userGuide/makingTheSiteSearchable.html) for more details. +**Specifies that the website should use MarkBind's search functionality.** Default: `true`. See [User Guide: Making the Site Searchable](makingTheSiteSearchable.html) for more details. diff --git a/docs/userGuide/syntax/links.mbdf b/docs/userGuide/syntax/links.mbdf index b2d6affb4f..af2fdc5b4e 100644 --- a/docs/userGuide/syntax/links.mbdf +++ b/docs/userGuide/syntax/links.mbdf @@ -45,15 +45,47 @@ MarkBind home is at [here][1] <div id="intraSiteLinks"> -Links to files of the generated site (e.g., an HTML page or an image file) should be specified as absolute paths and should start with {{ showBaseUrlCode }} (which represents the root directory of the project). +Links to files of the generated site (e.g., an HTML page or an image file) can be specified either as relative paths or absolute paths. +Absolute paths: <div class="indented"> +Links should start with {{ showBaseUrlCode }} (which represents the root directory of the project). {{ icon_example }} Here's how to specify a link to (1) a page, and (2) an image, using the {{ showBaseUrlCode }}: -1. <code>Click [here]({<span></span>{ baseUrl }}/userGuide/reusingContents.html).</code> +1. <code>Click [here]({{ showBaseUrlCode }}/userGuide/reusingContents.html).</code> 2. `![](`{{ showBaseUrlCode }}`/images/preview.png)` +</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: +``` +c:/course/ + ├── textbook/ + | ├── subsite.md + | ├── image.png + | └── site.json + ├── index.md + └── site.json +``` + +Within `textbook/subsite.md`, we can refer to the image using: +```html +<img src="image.png" /> +``` +Within `index.md`, we can also display the image using +```html +<img src="textbook/image.png" /> +``` +or by including `subsite.md`: +``` +<include src="textbook/subsite.md" /> +``` </div> </div> diff --git a/docs/userGuide/tweakingThePageStructure.md b/docs/userGuide/tweakingThePageStructure.md index 6b6f3ff557..0d5986775d 100644 --- a/docs/userGuide/tweakingThePageStructure.md +++ b/docs/userGuide/tweakingThePageStructure.md @@ -9,7 +9,7 @@ </frontmatter> <span id="link" class="d-none"> -<md>[_User Guide → {{ title }}_]({{ baseUrl }}/userGuide/{{ filename }}.html)</md> +<md>[_User Guide → {{ title }}_]({{ filename }}.html)</md> </span> <include src="../common/header.md" /> diff --git a/docs/userGuide/usingComponents.md b/docs/userGuide/usingComponents.md index 131a4cbf80..ed6739e2f6 100644 --- a/docs/userGuide/usingComponents.md +++ b/docs/userGuide/usingComponents.md @@ -9,7 +9,7 @@ </frontmatter> <span id="link" class="d-none"> -<md>[_User Guide → {{ title }}_]({{ baseUrl }}/userGuide/{{ filename }}.html)</md> +<md>[_User Guide → {{ title }}_]({{ filename }}.html)</md> </span> <include src="../common/header.md" /> diff --git a/docs/userGuide/usingHtmlJavaScriptCss.md b/docs/userGuide/usingHtmlJavaScriptCss.md index 61ce9e81f2..06a2dcf723 100644 --- a/docs/userGuide/usingHtmlJavaScriptCss.md +++ b/docs/userGuide/usingHtmlJavaScriptCss.md @@ -8,7 +8,7 @@ </frontmatter> <span id="link" class="d-none"> -<md>[_User Guide → {{ title }}_]({{ baseUrl }}/userGuide/{{ filename }}.html)</md> +<md>[_User Guide → {{ title }}_]({{ filename }}.html)</md> </span> <include src="../common/header.md" />