diff --git a/docs/_markbind/layouts/default.md b/docs/_markbind/layouts/default.md new file mode 100644 index 0000000000..87867be618 --- /dev/null +++ b/docs/_markbind/layouts/default.md @@ -0,0 +1,9 @@ + + +
+
+ {{ content }} +
+
+ + diff --git a/docs/_markbind/layouts/default/footer.md b/docs/_markbind/layouts/default/footer.md deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/docs/_markbind/layouts/default/head.md b/docs/_markbind/layouts/default/head.md deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/docs/_markbind/layouts/default/navigation.md b/docs/_markbind/layouts/default/navigation.md deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/docs/_markbind/layouts/default/scripts.js b/docs/_markbind/layouts/default/scripts.js deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/docs/_markbind/layouts/default/styles.css b/docs/_markbind/layouts/default/styles.css deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/docs/_markbind/layouts/devGuide.md b/docs/_markbind/layouts/devGuide.md new file mode 100644 index 0000000000..27be08c93d --- /dev/null +++ b/docs/_markbind/layouts/devGuide.md @@ -0,0 +1,31 @@ + + +
+ +
+ {{ content }} +
+ +
+ + diff --git a/docs/_markbind/layouts/devGuide/footer.md b/docs/_markbind/layouts/devGuide/footer.md deleted file mode 100644 index 4e2b2c711b..0000000000 --- a/docs/_markbind/layouts/devGuide/footer.md +++ /dev/null @@ -1,5 +0,0 @@ -
-
- [Generated by {{MarkBind}} on {{timestamp}}] -
-
diff --git a/docs/_markbind/layouts/devGuide/header.md b/docs/_markbind/layouts/devGuide/header.md deleted file mode 100644 index 2a771742cb..0000000000 --- a/docs/_markbind/layouts/devGuide/header.md +++ /dev/null @@ -1,19 +0,0 @@ -
- - - -
  • HOME
    • - - -
  • SHOWCASE
    • -
  • ABOUT
    • -
  • - :fab-github: -
    • -
  • -
    - -
    -
    • -     -
    diff --git a/docs/_markbind/layouts/devGuide/navigation.md b/docs/_markbind/layouts/devGuide/navigation.md deleted file mode 100644 index 449f330023..0000000000 --- a/docs/_markbind/layouts/devGuide/navigation.md +++ /dev/null @@ -1,13 +0,0 @@ - - -Developer Guide - -* [Contributing]({{baseUrl}}/devGuide/devGuide.html) -* [Setting up]({{baseUrl}}/devGuide/settingUp.html) -* [Workflow]({{baseUrl}}/devGuide/workflow.html) -* [Design]({{baseUrl}}/devGuide/design.html) -* [Writing Plugins]({{baseUrl}}/devGuide/writingPlugins.html) -* [Project management]({{baseUrl}}/devGuide/projectManagement.html) -* Appendices :expanded: - * [Style guides]({{baseUrl}}/devGuide/styleGuides.html) - diff --git a/docs/_markbind/footers/footer.md b/docs/_markbind/layouts/footers/footer.mbdf similarity index 100% rename from docs/_markbind/footers/footer.md rename to docs/_markbind/layouts/footers/footer.mbdf diff --git a/docs/_markbind/headers/header.md b/docs/_markbind/layouts/headers/header.mbdf similarity index 97% rename from docs/_markbind/headers/header.md rename to docs/_markbind/layouts/headers/header.mbdf index 6a1af8813a..761b77b13b 100644 --- a/docs/_markbind/headers/header.md +++ b/docs/_markbind/layouts/headers/header.mbdf @@ -1,5 +1,8 @@ -
    + + + +
  • HOME
    • diff --git a/docs/_markbind/layouts/userGuide/navigation.md b/docs/_markbind/layouts/userGuide.md similarity index 74% rename from docs/_markbind/layouts/userGuide/navigation.md rename to docs/_markbind/layouts/userGuide.md index 6940db8f38..57459b8ebb 100644 --- a/docs/_markbind/layouts/userGuide/navigation.md +++ b/docs/_markbind/layouts/userGuide.md @@ -1,7 +1,12 @@ - - -User Guide + +
    + +
    + {{ content }} +
    + +
    + + diff --git a/docs/_markbind/layouts/userGuide/footer.md b/docs/_markbind/layouts/userGuide/footer.md deleted file mode 100644 index 4e2b2c711b..0000000000 --- a/docs/_markbind/layouts/userGuide/footer.md +++ /dev/null @@ -1,5 +0,0 @@ -
    -
    - [Generated by {{MarkBind}} on {{timestamp}}] -
    -
    diff --git a/docs/_markbind/layouts/userGuide/header.md b/docs/_markbind/layouts/userGuide/header.md deleted file mode 100644 index 2a771742cb..0000000000 --- a/docs/_markbind/layouts/userGuide/header.md +++ /dev/null @@ -1,19 +0,0 @@ -
    - - - -
  • HOME
    • - - -
  • SHOWCASE
    • -
  • ABOUT
    • -
  • - :fab-github: -
    • -
  • -
    - -
    -
    • -     -
    diff --git a/docs/_markbind/navigation/devGuideSections.md b/docs/_markbind/navigation/devGuideSections.md deleted file mode 100644 index a42eee2bb6..0000000000 --- a/docs/_markbind/navigation/devGuideSections.md +++ /dev/null @@ -1,9 +0,0 @@ - - -Developer Guide - -* [Developer Guide]({{baseUrl}}/devGuide/devGuide.html) -* [Maintainer Guide]({{baseUrl}}/devGuide/maintainerGuide.html) -* [Contributing]({{baseUrl}}/devGuide/contributing.html) - * [Code of Conduct]({{baseUrl}}/devGuide/contributing/code-of-conduct.html) - diff --git a/docs/_markbind/navigation/userGuideSections.md b/docs/_markbind/navigation/userGuideSections.md deleted file mode 100644 index 5b93269cbb..0000000000 --- a/docs/_markbind/navigation/userGuideSections.md +++ /dev/null @@ -1,28 +0,0 @@ - - -User Guide - -* [Getting Started]({{baseUrl}}/userGuide/gettingStarted.html) -* [Authoring Contents]({{baseUrl}}/userGuide/authoringContents.html) :expanded: - * [Adding Pages]({{baseUrl}}/userGuide/addingPages.html) - * [MarkBind Syntax Overview]({{baseUrl}}/userGuide/markBindSyntaxOverview.html) - * [Formatting Contents]({{baseUrl}}/userGuide/formattingContents.html) - * [Inserting PlantUML Diagrams]({{baseUrl}}/userGuide/puml.html) - * [Using Components]({{baseUrl}}/userGuide/usingComponents.html) - * [Using HTML, JavaScript, CSS]({{baseUrl}}/userGuide/usingHtmlJavaScriptCss.html) - * [Using Plugins]({{baseUrl}}/userGuide/usingPlugins.html) - * [Tweaking the Page Structure]({{baseUrl}}/userGuide/tweakingThePageStructure.html) - * [Reusing Contents]({{baseUrl}}/userGuide/reusingContents.html) - * [Making the Site Searchable]({{baseUrl}}/userGuide/makingTheSiteSearchable.html) -* [Deploying the Site]({{baseUrl}}/userGuide/deployingTheSite.html) -* [MarkBind in the Project Workflow]({{baseUrl}}/userGuide/markBindInTheProjectWorkflow.html) -* [Themes]({{baseUrl}}/userGuide/themes.html) -* References :expanded: - * [CLI Commands]({{baseUrl}}/userGuide/cliCommands.html) - * [Reader-Facing Features]({{baseUrl}}/userGuide/readerFacingFeatures.html) - * [Full Syntax Reference]({{baseUrl}}/userGuide/fullSyntaxReference.html) - * [Syntax Cheat Sheet]({{baseUrl}}/userGuide/syntaxCheatSheet.html) - * [Site Configuration]({{baseUrl}}/userGuide/siteConfiguration.html) - * [Tips & Tricks]({{baseUrl}}/userGuide/tipsAndTricks.html) - * [Glossary]({{baseUrl}}/userGuide/glossary.html) - diff --git a/docs/about.md b/docs/about.md index 7de537237f..254dcca913 100644 --- a/docs/about.md +++ b/docs/about.md @@ -1,7 +1,5 @@ title: "About Us" - header: header.md - footer: footer.md # About Us diff --git a/docs/css/main.css b/docs/css/main.css index d5946f82b0..e811e744f0 100644 --- a/docs/css/main.css +++ b/docs/css/main.css @@ -12,3 +12,135 @@ mark { .theme-card img { width: 100%; } + +/* Scrollbar */ + +.slim-scroll::-webkit-scrollbar { + width: 5px; +} + +.slim-scroll::-webkit-scrollbar-thumb { + background: #808080; + border-radius: 20px; +} + +.slim-scroll::-webkit-scrollbar-track { + background: transparent; + border-radius: 20px; +} + +.slim-scroll-blue::-webkit-scrollbar { + width: 5px; +} + +.slim-scroll-blue::-webkit-scrollbar-thumb { + background: #00b0ef; + border-radius: 20px; +} + +.slim-scroll-blue::-webkit-scrollbar-track { + background: transparent; + border-radius: 20px; +} + +/* Layout containers */ + +#flex-body { + display: flex; + flex: 1; +} + +#content-wrapper { + flex: 1; + margin: 0 auto; + min-width: 0; + max-width: 1000px; + padding: 0.8rem 20px 0 20px; + transition: 0.4s; + -webkit-transition: 0.4s; +} + +#site-nav, +#page-nav { + position: sticky; + top: 0; + flex: 0 0 auto; + padding-top: 1rem; + max-width: 300px; + width: 300px; +} + +#site-nav { + display: flex; + flex-direction: column; + border-right: 1px solid lightgrey; + padding-bottom: 20px; + z-index: 999; + max-height: 100vh; +} + +.site-nav-top { + margin-top: 0.8rem; + padding: 0 12px 12px 12px; +} + +.nav-component { + padding: 0.8rem 12px 0 12px; + overflow-y: auto; +} + +#page-nav { + display: block; + max-height: 90vh; +} + +#page-nav .nav-component { + border-left: 1px solid lightgrey; + max-height: 90vh; +} + +@media screen and (max-width: 1299.98px) { + #page-nav { + display: none; + } +} + +/* Bootstrap medium(md) responsive breakpoint */ +@media screen and (max-width: 991.98px) { + #site-nav { + display: none; + } + + footer { + margin-left: 60px; + } +} + +/* Bootstrap small(sm) responsive breakpoint */ +@media (max-width: 767.98px) { + #content-wrapper { + padding: 0 10px; + } +} + +/* Bootstrap extra small(xs) responsive breakpoint */ +@media screen and (max-width: 575.98px) { + #site-nav { + display: none; + } + + footer { + margin-left: 0; + } +} + +/* Hide site navigation when printing */ +@media print { + #site-nav { + display: none; + } + + #page-nav { + display: none; + } +} diff --git a/docs/devGuide/design.md b/docs/devGuide/design.md index c5c91f2b66..decc972ace 100644 --- a/docs/devGuide/design.md +++ b/docs/devGuide/design.md @@ -3,7 +3,7 @@ title: "{{ title }}" - layout: devGuide + layout: devGuide.md pageNav: default diff --git a/docs/devGuide/devGuide.md b/docs/devGuide/devGuide.md index 957deb45c5..003d248ca1 100644 --- a/docs/devGuide/devGuide.md +++ b/docs/devGuide/devGuide.md @@ -3,7 +3,7 @@ title: "{{ title }}" - layout: devGuide + layout: devGuide.md

    Developer guide

    diff --git a/docs/devGuide/projectManagement.md b/docs/devGuide/projectManagement.md index fbcdd70cce..2f1a7e5af7 100644 --- a/docs/devGuide/projectManagement.md +++ b/docs/devGuide/projectManagement.md @@ -3,7 +3,7 @@ title: "{{ title }}" - layout: devGuide + layout: devGuide.md pageNav: default diff --git a/docs/devGuide/settingUp.md b/docs/devGuide/settingUp.md index 8717bd8304..baa996637b 100644 --- a/docs/devGuide/settingUp.md +++ b/docs/devGuide/settingUp.md @@ -3,7 +3,7 @@ title: "{{ title }}" - layout: devGuide + layout: devGuide.md # {{ title }} diff --git a/docs/devGuide/styleGuides.md b/docs/devGuide/styleGuides.md index 1541535e6e..b7af16d367 100644 --- a/docs/devGuide/styleGuides.md +++ b/docs/devGuide/styleGuides.md @@ -3,7 +3,7 @@ title: "{{ title }}" - layout: devGuide + layout: devGuide.md pageNav: default diff --git a/docs/devGuide/workflow.md b/docs/devGuide/workflow.md index 2f2c22d02d..4908744556 100644 --- a/docs/devGuide/workflow.md +++ b/docs/devGuide/workflow.md @@ -3,7 +3,7 @@ title: "{{ title }}" - layout: devGuide + layout: devGuide.md pageNav: default diff --git a/docs/devGuide/writingPlugins.md b/docs/devGuide/writingPlugins.md index 2267aaf313..3900457f6d 100644 --- a/docs/devGuide/writingPlugins.md +++ b/docs/devGuide/writingPlugins.md @@ -3,7 +3,7 @@ title: "{{ title }}" - layout: devGuide + layout: devGuide.md pageNav: default diff --git a/docs/index.md b/docs/index.md index 3652592f59..c8e85b9476 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,7 +1,5 @@ title: "Generate More Dynamic Websites from Markdown Text" - header: header.md - footer: footer.md
    diff --git a/docs/showcase.md b/docs/showcase.md index 83b546f1a2..e88bcafe8f 100644 --- a/docs/showcase.md +++ b/docs/showcase.md @@ -1,7 +1,5 @@ title: "Showcase" - header: header.md - footer: footer.md # Examples of MarkBind Websites diff --git a/docs/userGuide/addingPages.md b/docs/userGuide/addingPages.md index 514ddc6973..af586afe94 100644 --- a/docs/userGuide/addingPages.md +++ b/docs/userGuide/addingPages.md @@ -4,7 +4,7 @@ title: "User Guide: {{ title }}" - layout: userGuide + layout: userGuide.md diff --git a/docs/userGuide/authoringContents.md b/docs/userGuide/authoringContents.md index b39888ac7e..7fee124788 100644 --- a/docs/userGuide/authoringContents.md +++ b/docs/userGuide/authoringContents.md @@ -3,7 +3,7 @@ title: "User Guide: {{ title }}" - layout: userGuide + layout: userGuide.md # {{ title }} diff --git a/docs/userGuide/cliCommands.md b/docs/userGuide/cliCommands.md index 87b4e5a053..e5b3c949df 100644 --- a/docs/userGuide/cliCommands.md +++ b/docs/userGuide/cliCommands.md @@ -1,6 +1,6 @@ title: "User Guide: Command Line Interface (CLI)" - layout: userGuide + layout: userGuide.md pageNav: default diff --git a/docs/userGuide/deployingTheSite.md b/docs/userGuide/deployingTheSite.md index bb3292f34e..e21fffa6c1 100644 --- a/docs/userGuide/deployingTheSite.md +++ b/docs/userGuide/deployingTheSite.md @@ -4,7 +4,7 @@ title: "User Guide: {{ title }}" - layout: userGuide + layout: userGuide.md pageNav: default diff --git a/docs/userGuide/formattingContents.md b/docs/userGuide/formattingContents.md index 653b410bfd..c7f6023fdb 100644 --- a/docs/userGuide/formattingContents.md +++ b/docs/userGuide/formattingContents.md @@ -4,7 +4,7 @@ title: "User Guide: {{ title }}" - layout: userGuide + layout: userGuide.md pageNav: 2 diff --git a/docs/userGuide/fullSyntaxReference.md b/docs/userGuide/fullSyntaxReference.md index 752c4a944d..640e371791 100644 --- a/docs/userGuide/fullSyntaxReference.md +++ b/docs/userGuide/fullSyntaxReference.md @@ -1,6 +1,6 @@ title: "User Guide: Full Syntax Reference" - layout: userGuide + layout: userGuide.md # Full Syntax Reference @@ -28,8 +28,6 @@ frontmatter : ['Front Matter', ['other']], includes : ['Includes', ['other']], keywords : ['Keywords', ['other']], - pageHead : ['Page Head', ['other']], - pageLayouts : ['Page Layouts', ['other']], tags : ['Tags', ['other']], variables : ['Variables', ['other']], @@ -37,20 +35,18 @@ boxes : ['Boxes', ['component', 'reader-facing']], diagrams : ['Diagrams', ['component', 'reader-facing']], dropdowns : ['Dropdowns', ['component', 'reader-facing']], - footers : ['Footers', ['other', 'reader-facing']], - headers: ['Headers', ['other', 'reader-facing']], modals : ['Modals', ['component', 'reader-facing']], navBars : ['Nav Bars', ['component', 'reader-facing']], - pageNavigationMenus : ['Page Navigation Menus', ['component', 'reader-facing']], panels : ['Panels', ['component', 'reader-facing']], pictures : ['Pictures', ['component', 'reader-facing']], popovers : ['Popovers', ['component', 'reader-facing']], questions : ['Questions and Quizzes', ['component', 'reader-facing']], searchBars : ['Search Bars', ['component', 'reader-facing']], - siteNavigationMenus : ['Site Navigation Menus', ['component', 'reader-facing']], tabs : ['Tabs', ['component', 'reader-facing']], thumbnails : ['Thumbnails', ['component', 'reader-facing']], - tooltips : ['Tooltips', ['component', 'reader-facing']] + tooltips : ['Tooltips', ['component', 'reader-facing']], + siteNavigationMenus : ['Site Navigation Menus', ['component', 'reader-facing']], + pageNavigationMenus : ['Page Navigation Menus', ['component', 'reader-facing']] } %} {% for topic in syntax_topics | dictsort %} diff --git a/docs/userGuide/gettingStarted.md b/docs/userGuide/gettingStarted.md index d26426bb9b..3d02aedcc1 100644 --- a/docs/userGuide/gettingStarted.md +++ b/docs/userGuide/gettingStarted.md @@ -3,7 +3,7 @@ title: "User Guide - {{ title }}" - layout: userGuide + layout: userGuide.md # {{ title }} diff --git a/docs/userGuide/glossary.md b/docs/userGuide/glossary.md index bef0d55369..f6e9234b1b 100644 --- a/docs/userGuide/glossary.md +++ b/docs/userGuide/glossary.md @@ -1,6 +1,6 @@ title: "Glossary" - layout: userGuide + layout: userGuide.md #### Live Preview :fas-sync: diff --git a/docs/userGuide/makingTheSiteSearchable.md b/docs/userGuide/makingTheSiteSearchable.md index b8c6564321..eaf3bfec92 100644 --- a/docs/userGuide/makingTheSiteSearchable.md +++ b/docs/userGuide/makingTheSiteSearchable.md @@ -6,7 +6,7 @@ title: "User Guide: {{ title }}" - layout: userGuide + layout: userGuide.md pageNav: 2 diff --git a/docs/userGuide/markBindInTheProjectWorkflow.md b/docs/userGuide/markBindInTheProjectWorkflow.md index b66c91206b..886c0a922b 100644 --- a/docs/userGuide/markBindInTheProjectWorkflow.md +++ b/docs/userGuide/markBindInTheProjectWorkflow.md @@ -4,7 +4,7 @@ title: "User Guide: {{ title }}" - layout: userGuide + layout: userGuide.md diff --git a/docs/userGuide/markBindSyntaxOverview.md b/docs/userGuide/markBindSyntaxOverview.md index 393ae4becb..1c09e8bd44 100644 --- a/docs/userGuide/markBindSyntaxOverview.md +++ b/docs/userGuide/markBindSyntaxOverview.md @@ -4,7 +4,7 @@ title: "User Guide: {{ title }} " - layout: userGuide + layout: userGuide.md diff --git a/docs/userGuide/plugins/tags.mbdf b/docs/userGuide/plugins/tags.mbdf index e287bbd896..40a0164c00 100644 --- a/docs/userGuide/plugins/tags.mbdf +++ b/docs/userGuide/plugins/tags.mbdf @@ -1,4 +1,4 @@ -### Plugin: Tags +{{ topHeadingLevel or "###" }} Plugin: Tags With this plugin you can use tags to selectively filter content when building a site. diff --git a/docs/userGuide/readerFacingFeatures.md b/docs/userGuide/readerFacingFeatures.md index 95484a4ea5..9b2ddfb61a 100644 --- a/docs/userGuide/readerFacingFeatures.md +++ b/docs/userGuide/readerFacingFeatures.md @@ -1,6 +1,6 @@ title: "User Guide: Reader-Facing Features" - layout: userGuide + layout: userGuide.md # Reader-Facing Features diff --git a/docs/userGuide/reusingContents.md b/docs/userGuide/reusingContents.md index 35225b068d..c2a3d9521f 100644 --- a/docs/userGuide/reusingContents.md +++ b/docs/userGuide/reusingContents.md @@ -4,7 +4,7 @@ title: "User Guide: {{ title }}" - layout: userGuide + layout: userGuide.md pageNav: 4 diff --git a/docs/userGuide/settingSiteProperties.md b/docs/userGuide/settingSiteProperties.md index 25a468266a..8fa31a9237 100644 --- a/docs/userGuide/settingSiteProperties.md +++ b/docs/userGuide/settingSiteProperties.md @@ -4,7 +4,7 @@ title: "User Guide: {{ title }}" - layout: userGuide + layout: userGuide.md {% from "njk/common.njk" import embed, previous_next %} diff --git a/docs/userGuide/siteJsonFile.md b/docs/userGuide/siteJsonFile.md index e7147ebb18..a8a932ed58 100644 --- a/docs/userGuide/siteJsonFile.md +++ b/docs/userGuide/siteJsonFile.md @@ -1,6 +1,6 @@ title: "site.json File" - layout: userGuide + layout: userGuide.md keywords: site.json diff --git a/docs/userGuide/syntax/code.mbdf b/docs/userGuide/syntax/code.mbdf index fa4bd98ef5..5c3ea0a45e 100644 --- a/docs/userGuide/syntax/code.mbdf +++ b/docs/userGuide/syntax/code.mbdf @@ -19,7 +19,7 @@ Features: ##### Syntax coloring To enable syntax coloring, specify a language next to the backticks before the fenced code block. - +
    ```xml @@ -29,7 +29,7 @@ To enable syntax coloring, specify a language next to the backticks before the f ``` - +
    ##### Line numbering Line numbers are provided by default. To hide line numbers, add the class `no-line-numbers` to the code block as below @@ -77,6 +77,7 @@ This variant's format is very similar to the previous, but instead use line-slic For ranges, you only need to use line-slices on either ends. + ```java {highlight-lines="1,3[:],6-8,10[:]-12"} import java.util.List; diff --git a/docs/userGuide/syntax/dates.mbdf b/docs/userGuide/syntax/dates.mbdf index 3c74305454..d07824f914 100644 --- a/docs/userGuide/syntax/dates.mbdf +++ b/docs/userGuide/syntax/dates.mbdf @@ -7,12 +7,12 @@ **Syntax:** {{ njcode('baseDate | date(format, daysToAdd)') }} - +
    20 days after 1st Jan 2020: {{ njcode('"2020-01-01" | date("ddd, Do MMM, YYYY", 20) ') }} :glyphicon-arrow-right: {{ "2020-01-01" | date("ddd, Do MMM, YYYY", 20) }} - +
    diff --git a/docs/userGuide/syntax/diagrams.mbdf b/docs/userGuide/syntax/diagrams.mbdf index 6173941a4e..adf1af5ae5 100644 --- a/docs/userGuide/syntax/diagrams.mbdf +++ b/docs/userGuide/syntax/diagrams.mbdf @@ -13,7 +13,7 @@ must be installed to use this feature** - +
    ``` @@ -34,7 +34,7 @@ return success - +
         diff --git a/docs/userGuide/syntax/emoji.mbdf b/docs/userGuide/syntax/emoji.mbdf index 739d6b81d0..9c4b65065d 100644 --- a/docs/userGuide/syntax/emoji.mbdf +++ b/docs/userGuide/syntax/emoji.mbdf @@ -1,13 +1,13 @@ ## Emoji - +
    markdown :+1: :exclamation: :x: :construction: - +
    diff --git a/docs/userGuide/syntax/footers.mbdf b/docs/userGuide/syntax/footers.mbdf deleted file mode 100644 index 28f047edb3..0000000000 --- a/docs/userGuide/syntax/footers.mbdf +++ /dev/null @@ -1,45 +0,0 @@ -## Footers - -**You can specify a page footer** using a footer file. - -You can save multiple footer files in the `_markbind/footers` folder and specify it in the `` of the pages in which it should appear. - -
    - -{{ icon_example }} -**`_markbind/footers/`**`commonFooter.md`: -```html -
    - This page is not updated anymore! -
    -``` -In the page that you want to include the footer: -```html - - footer: commonFooter.md - -``` -
    - -Notes: -- Any inline footers will be removed by MarkBind to ensure compatibility with footer files. -- If a [Layout]({{ baseUrl }}/userGuide/tweakingThePageStructure.html#page-layouts) is specified, the footer file specified in the `` will override the footer within the Layout. -- If you wish to use a Layout but exclude its footer file, specify `footer: none` in the `` of the page. -- [MarkBind Components]({{ baseUrl }}/userGuide/usingComponents.html) and [`` tags]({{ baseUrl }}/userGuide/reusingContents.html#the-include-tag) are not supported in footers. - - -```html -
    - This page is not updated anymore! -
    -``` -```html - - footer: commonFooter.md - -``` -     - - -You can see an example of a footer ==at the bottom== of this page. - diff --git a/docs/userGuide/syntax/frontmatter.mbdf b/docs/userGuide/syntax/frontmatter.mbdf index b4191a6330..484dfdb95b 100644 --- a/docs/userGuide/syntax/frontmatter.mbdf +++ b/docs/userGuide/syntax/frontmatter.mbdf @@ -26,7 +26,7 @@ Should you need more expressive formatting, or encounter any issues when formatt **Page properties:** * **`title`**: The title of the page. Will be used as the `` attribute of the HTML page generated. -* Other properties such as `keywords`, `layout`, `head` etc. will be explained in other places of this user guide. +* Other properties such as `keywords`, `layout`, etc. will be explained in other places of this user guide. <include src="../siteJsonFile.md#page-property-overriding" /> diff --git a/docs/userGuide/syntax/headers.mbdf b/docs/userGuide/syntax/headers.mbdf deleted file mode 100644 index bcf1e5525a..0000000000 --- a/docs/userGuide/syntax/headers.mbdf +++ /dev/null @@ -1,61 +0,0 @@ -## Headers - -**You can specify a <tooltip content="Content to be placed at the top of a page.">page header</tooltip>** above your page contents and <tooltip content="Site Navigation and <br>Page Navigation menus">navigation menus</tooltip> using a header file. - -You can save multiple header files in the `_markbind/headers` folder and specify it in the `<frontmatter>` of the pages in which it should appear. - -<div class="indented"> - -{{ icon_example }} -**`_markbind/headers/`**`welcomeBanner.md`: -```html -<header> - <div class="bg-primary display-4 text-center text-white"> - Welcome! - </div> -</header> -``` -In the page that you want to include the header: -```html -<frontmatter> - header: welcomeBanner.md -</frontmatter> -``` -</div> - -You can fix the header to be always on the top by add `fixed` attribute to the `<header>` tag of your header file: - -{{ icon_example }} -**`_markbind/headers/`**`header.md`: -```html -<header fixed> - <!--Normal header stuff goes here--> -</header> - -``` - -Notes: -- Any inline headers will be removed by MarkBind to ensure compatibility with header files. -- If a [Layout]({{ baseUrl }}/userGuide/tweakingThePageStructure.html#page-layouts) is specified, the header file specified in the `<frontmatter>` will override the header within the Layout. -- If you wish to use a Layout but exclude its header file, specify `header: none` in the `<frontmatter>` of the page. -- [MarkBind Components]({{ baseUrl }}/userGuide/usingComponents.html) and [`<include>` tags]({{ baseUrl }}/userGuide/reusingContents.html#the-include-tag) are not supported in headers. - -<span id="short" class="d-none"> -```html -<header> - <div class="bg-primary display-4 text-center text-white" style="height: 200px;"> - Welcome! - </div> -</header> -``` -```html -<frontmatter> - header: welcomeBanner.md -</frontmatter> -``` -</span> -<span id="examples" class="d-none"> - <div class="bg-primary display-4 text-center text-white" style="height: 150px;"> - Content to be placed at the top of your page. - </div> -</span> diff --git a/docs/userGuide/syntax/headings.mbdf b/docs/userGuide/syntax/headings.mbdf index c46735f798..4e0db1e18b 100644 --- a/docs/userGuide/syntax/headings.mbdf +++ b/docs/userGuide/syntax/headings.mbdf @@ -2,7 +2,7 @@ You can prepend the heading text with 1-6 `#` characters to indicate headings of levels 1-6. -<span id="main-example"> +<div id="main-example"> <include src="codeAndOutput.md" boilerplate > <variable name="highlightStyle">markdown</variable> <variable name="code"> @@ -11,7 +11,7 @@ You can prepend the heading text with 1-6 `#` characters to indicate headings of ###### Heading level 6 </variable> </include> -</span> +</div> {{ icon_info }} **MarkBind auto-generates anchors for all headings.**<br> If the heading text is `Foo Bar (Goo)`, the ID of the generated anchor will be `foo-bar-goo` (all lower case, special characters omitted, joined by `-`). diff --git a/docs/userGuide/syntax/links.mbdf b/docs/userGuide/syntax/links.mbdf index 6080483a42..65a285827a 100644 --- a/docs/userGuide/syntax/links.mbdf +++ b/docs/userGuide/syntax/links.mbdf @@ -2,14 +2,14 @@ Basic style: -<span id="main-example"> +<div id="main-example"> <include src="codeAndOutput.md" boilerplate > <variable name="highlightStyle">markdown</variable> <variable name="code"> MarkBind home is at [here](https://markbind.org). </variable> </include> -</span> +</div> _Reference style_ links (i.e., specify the URL in a separate place): diff --git a/docs/userGuide/syntax/navBars.mbdf b/docs/userGuide/syntax/navBars.mbdf index 4db3cc8878..5707b0c9fb 100644 --- a/docs/userGuide/syntax/navBars.mbdf +++ b/docs/userGuide/syntax/navBars.mbdf @@ -80,7 +80,7 @@ If you wish to further customize your navbar beyond the primary, dark, and light ****Navbar Link Highlighting**** ```html -{% include "_markbind/headers/header.md" %} +{% include "_markbind/layouts/headers/header.mbdf" %} ``` ****Highlight Options**** diff --git a/docs/userGuide/syntax/pageHead.mbdf b/docs/userGuide/syntax/pageHead.mbdf deleted file mode 100644 index 6355c147d6..0000000000 --- a/docs/userGuide/syntax/pageHead.mbdf +++ /dev/null @@ -1,75 +0,0 @@ -## Page `<head>` - -**MarkBind allows you to insert code into the `<head>` section of the generated HTML page**, for example, to add links to custom JavaScript or CSS files. - -Steps: -1. Put the code you want to insert into the `<head>` into a file inside the `_markbind/head` directory. -2. Specify the file as an attribute named `head` in the `<frontmatter>` of the page. - -<div class="indented"> - -{{ icon_example }} Suppose you want to insert the code below into the `<head>` of a page, and you have saved the code as **`_markbind/head/`**`myCustomLinks.md`: - -```html{.no-line-numbers} -<script src="{{ baseUrl }}/js/myCustomScript.js"></script> -<link rel="stylesheet" href="{{ baseUrl }}/css/main.css"> -<link rel="stylesheet" href="{{ baseUrl }}/css/extra.css"> -``` - -To specify that you want to insert `myCustomLinks.md` into the `<head>` of `myPage.html`, update the front matter of the `myPage.md` as follows: - ```html - <frontmatter> - head: myCustomLinks.md - </frontmatter> - ... - ``` - -</div> - -**All content is inserted at the bottom of the `<head>` tag by default.** You can use the optional `<head-top>` tag to specify content that should be inserted at the top of the `<head>` tag instead. - -<div class="indented"> - -{{ icon_example }} Here's how you can force the line `<script ... > ... </script>` to be inserted at the top of the `<head>` section. - -```html {.no-line-numbers highlight-lines="1,3"} -<head-top> - <script src="{{ baseUrl }}/js/myCustomScript.js"></script> -</head-top> -<link rel="stylesheet" href="{{ baseUrl }}/css/main.css"> -<link rel="stylesheet" href="{{ baseUrl }}/css/extra.css"> -``` - -</div> - -**Multiple head files can be included** within a page by providing a comma separated list. They will be added to the `<head>` in the order in which they are listed. - -<div class="indented"> - -{{ icon_example }} -```html -<frontmatter> - head: customStyles.md, extraScripts.md -</frontmatter> -``` -</div> -<span id="short" class="d-none"> - -`_markbind/head/myCustomLinks.md`: - -```html{.no-line-numbers highlight-lines="1,3"} -<head-top> -<script src="`{{ baseUrl }}`/js/myCustomScript.js"></script> -</head-top> -<link rel="stylesheet" href="`{{ baseUrl }}`/css/main.css"> -<link rel="stylesheet" href="`{{ baseUrl }}`/css/extra.css"> -``` - -```html - <frontmatter> - head: myCustomLinks.md - </frontmatter> -``` -</span> - -If you wish to use a [Layout]({{ baseUrl }}/userGuide/tweakingThePageStructure.html#page-layouts) but exclude its head file, specify `head: none` in the `<frontmatter>` of the page. diff --git a/docs/userGuide/syntax/pageLayouts.mbdf b/docs/userGuide/syntax/pageLayouts.mbdf deleted file mode 100644 index 2f3868a302..0000000000 --- a/docs/userGuide/syntax/pageLayouts.mbdf +++ /dev/null @@ -1,119 +0,0 @@ -## Page Layouts - -**A _layout_ is a set of page-tweaks that can be applied to a page (or group of pages) in one go.** - -A layout consists of the following files: -1. A header (filename: `header.md`) -1. A footer (filename: `footer.md`) -1. Tweaks to the `<head>` (`head.md`) -1. A site navigation menu (`navigation.md`) -1. An expressive layout template to embed your content (`page.md`) -1. Custom styles (`styles.css`) -1. Custom scripts (`scripts.js`) - -A layout is represented by a sub-directory in the `_markbind/layouts/` containing the files listed above. The name of the layout is same as the name of the sub-directory. - -To apply the layout, specify it as an attribute named `layout` in the `<frontmatter>` of each page, or in the `site.json`. - - -<div class="indented"> - -{{ icon_example }} Suppose you have a layout named `chapterLayout`. -```{.no-line-numbers} -<root>/_markbind/layouts/ - └── chapterLayout/ - ├── header.md - ├── footer.md - ├── head.md - ├── page.md - ├── navigation.md - ├── styles.css - └── scripts.js -``` -You can apply it to the `chapter.md` by setting its `<frontmatter>` as follows: -```html -<frontmatter> - layout: chapterLayout -</frontmatter> -... -``` -You can apply it to all `chapter.md` files by adding this entry to the `site.json`. - -```json -{ - "glob": "**/chapter.md", - "layout": "chapterLayout" -} -``` -</div> - -The layout specified in the `site.json` overrides the one specified in the `<frontmatter>`. - -Any files specified in `<frontmatter>` overrides the corresponding file in the layout applied. - -<div class="indented"> - -{{ icon_example }} Suppose a file has the following: -```html -<frontmatter> - layout: chapterLayout - head: myHead.md -</frontmatter> -... -``` -In this case `myHead.md` will override the `chapterLayout/head.md`. - -</div> - -**The layout named `default` (if any) is automatically applied to every single page.** When you `init` a MarkBind site, MarkBind also generates an empty `default` layout. - - -<span id="short" class="d-none"> - -```html -<frontmatter> - layout: chapterLayout -</frontmatter> -``` -</span> - -#### Using Expressive Layout Templates - -In the `page.md` file of your layouts, it should come with the following reserved variable: - -<box> - - {%raw%}`{{ MAIN_CONTENT_BODY }}`{%endraw%} -</box> - -which injects the actual page content in every page. This allows you to build layouts in different ways. - -{{ icon_example }} Adding statistics formula to the bottom of every page - - ```html {heading="index.md"} - #### Main content of your page - - Content of your page - ``` - - ```html {heading="page.md"} - {%raw%}{{ MAIN_CONTENT_BODY }}{%endraw%} - <panel header="Statistics Formula for the class" type="primary"> - <img src="path_to_your_formula.png" /> - </panel> - ``` - -Here's how the above content would appear: - -<box> -<i>index.html</i> -<br><br> - -#### Main content of your page - -Content of your page - -<panel header="Statistics Formula for the class" type="primary"> - <img src="extra/stats.png" width="420px" height="320px" /> -</panel> -</box> diff --git a/docs/userGuide/syntax/pageNavigationMenus.mbdf b/docs/userGuide/syntax/pageNavigationMenus.mbdf index f72f829a56..a650164193 100644 --- a/docs/userGuide/syntax/pageNavigationMenus.mbdf +++ b/docs/userGuide/syntax/pageNavigationMenus.mbdf @@ -1,15 +1,27 @@ ## Page Navigation Menus -**A _Page Navigation Menu_ (==_pageNav_ for short==) is a fixed menu on the ==right edge== of your page contents**. You can use a pageNav to show a list of the current page's headings. +<div id="content"> -Steps to add a pageNav: -1. Specify your pageNav within the `<frontmatter>` of a page with <tooltip content="The value `default` will use `headingIndexingLevel` within `site.json`.">`"default"`</tooltip> or a <tooltip content="HTML defines six levels of headings, numbered from <br>`1 to 6`.">`heading level`</tooltip>. -2. (Optional) You may also specify a page navigation title within `<frontmatter>` that will be placed at the top of the page navigation menu. +**A _Page Navigation Menu_ (==_pageNav_ for short==) a list of the current page's headings.** Page navigation menus are only available for use in [layouts]({{baseUrl}}/userGuide/tweakingThePageStructure.html#layouts). -<div class="indented"> +****Adding a pageNav**** + +1. **Specify the smallest heading level you want to be included** within the `<frontmatter>` of a page with <tooltip content="The value `default` will use `headingIndexingLevel` within `site.json`.">`"default"`</tooltip> or a <tooltip content="HTML defines six levels of headings, numbered from <br>`1 to 6`.">`heading level`</tooltip>. + + <box type="info" seamless> + + The `default` level uses the [`headingIndexingLevel` property]({{baseUrl}}/userGuide/siteJsonFile.html#headingindexinglevel) of your site configuration file. + </box> + +2. **(Optional) You may also specify a page navigation title** within `<frontmatter>` that will be placed at the top of the page navigation menu. + +3. **Position the page navigation menu** within your layout using the `{% raw %}{{ pageNav }}{% endraw %}` variable. + +<div id="short" class="indented"> {{ icon_example }} -In the page that you want to have page navigation: +In the page that you want to have page navigation, you may show only `<h1>` and `<h2>` headings in the pageNav, and set a custom pageNav title like so: + ```html <frontmatter> pageNav: 2 @@ -17,20 +29,21 @@ In the page that you want to have page navigation: </frontmatter> ``` -The example above will create a page navigation containing only heading levels of `1 and 2`. -</div> +Then, in your [layout file]({{baseUrl}}/userGuide/tweakingThePageStructure.html#layouts), use the `{% raw %}{{ pageNav }}{% endraw %}` variable to position the pageNav. -A pageNav has a fixed width of 300 pixels for its contents. It is [_responsive_](https://www.w3schools.com/html/html_responsive.asp) by design and will be completely hidden when the screen size is smaller than 1300 pixels. +{% if not doNotShowPageNav %} +{{ icon_example }} <trigger for="modal:page-nav-example">Example usage of the `{% raw %}{{ pageNav }}{% endraw %}` variable</trigger> -<span id="short" class="d-none"> +<modal header="Using the `pageNav` variable in a layout" id="modal:page-nav-example" large> +<include src="../tweakingThePageStructure.md#layout-code-snippet"> +<variable name="highlightLines">54</variable> +</include> +</modal> +{% endif %} -```html -<frontmatter> - pageNav: 2 - pageNavTitle: "Chapters of This Page" -</frontmatter> -``` -</span> +</div> + +</div> <span id="examples" class="d-none"> diff --git a/docs/userGuide/syntax/siteNavigationMenus.mbdf b/docs/userGuide/syntax/siteNavigationMenus.mbdf index 865f73d6e1..c5c501cf3e 100644 --- a/docs/userGuide/syntax/siteNavigationMenus.mbdf +++ b/docs/userGuide/syntax/siteNavigationMenus.mbdf @@ -1,154 +1,40 @@ ## Site Navigation Menus -**A _Site Navigation Menu_ (==_siteNav_ for short==) is a fixed menu on the ==left edge== of a page**, that can be used to show a road map of the main pages of your site. +<div id="content"> -Steps to add a siteNav: -1. Format your siteNav as an unordered Markdown list and save it inside the `_markbind/navigation` directory. -2. Specify the file as the value of the `siteNav` attribute in the `<frontmatter>` of the page. - -<div class="indented"> - -{{ icon_example }} Here is an example siteNav code saved in **`_markbind/navigation/`**`mySiteNav.md` file: - -```{.no-line-numbers} -* [:house: Home]({{ baseUrl }}/index.html) -* --- -* Docs - * [User Guide]({{ baseUrl }}/ug.html) - * [Dev Guide]({{ baseUrl }}/dg.html) -* [Search]({{ baseUrl }}/search.html) - * [Google Search](https://www.google.com/) - * [YouTube Search](https://www.youtube.com/) -* [Contact]({{ baseUrl }}/contact.html) -``` +**A _Site Navigation Menu_ (==_siteNav_ for short==) can be used to show a road map of the main pages of your site.** -Here's how another page can make use of the above siteNav: - -```html -<frontmatter> - siteNav: mySiteNav.md -</frontmatter> -... -``` - -And here's how the above siteNav would appear: - -<div style="width:300px;" class="mb-3"> -<ul class="site-nav-list site-nav-list-root"> - <li> - <div onclick="handleSiteNavClick(this)" class="site-nav-list-item-content site-nav-list-item-content-0"><a href="/index.html">🏠 Home</a></div> - </li> - <li> - <hr> - </li> - <li> - <div onclick="handleSiteNavClick(this)" class="site-nav-list-item-content site-nav-list-item-content-0">Docs - <i onclick="handleSiteNavClick(this.parentNode, false); event.stopPropagation();" class="site-nav-dropdown-btn-icon"><span aria-hidden="true" class="glyphicon glyphicon-menu-down"></span></i> - </div> - <ul class="site-nav-dropdown-container site-nav-list"> - <li> - <div onclick="handleSiteNavClick(this)" class="site-nav-list-item-content site-nav-list-item-content-1"><a href="/ug.html">User Guide</a></div> - </li> - <li> - <div onclick="handleSiteNavClick(this)" class="site-nav-list-item-content site-nav-list-item-content-1"><a href="/dg.html">Dev Guide</a></div> - </li> - </ul> - </li> - <li> - <div onclick="handleSiteNavClick(this)" class="site-nav-list-item-content site-nav-list-item-content-0"><a href="/search.html">Search</a> <i onclick="handleSiteNavClick(this.parentNode, false); event.stopPropagation();" class="site-nav-dropdown-btn-icon"><span aria-hidden="true" class="glyphicon glyphicon-menu-down"></span></i></div> - <ul class="site-nav-dropdown-container site-nav-list"> - <li> - <div onclick="handleSiteNavClick(this)" class="site-nav-list-item-content site-nav-list-item-content-1"><a href="https://www.google.com/">Google Search</a></div> - </li> - <li> - <div onclick="handleSiteNavClick(this)" class="site-nav-list-item-content site-nav-list-item-content-1"><a href="https://www.youtube.com/">YouTube Search</a></div> - </li> - </ul> - </li> - <li> - <div onclick="handleSiteNavClick(this)" class="site-nav-list-item-content site-nav-list-item-content-0"><a href="/contact.html">Contact</a></div> - </li> -</ul> +Steps to add a siteNav: +1. Format your siteNav as an unordered Markdown list +2. Include it under a `<site-nav>` element. + +<div id="short"> + +<include src="codeAndOutput.md" boilerplate > +<variable name="code"> +<site-nav> +* [**Getting Started**]({{baseUrl}}/userGuide/gettingStarted.html) +* **Authoring Contents** :expanded: + * [Overview]({{baseUrl}}/userGuide/authoringContents.html) + * [Adding Pages]({{baseUrl}}/userGuide/addingPages.html) + * [MarkBind Syntax Overview]({{baseUrl}}/userGuide/markBindSyntaxOverview.html) + * [Formatting Contents]({{baseUrl}}/userGuide/formattingContents.html) + * [Using Components]({{baseUrl}}/userGuide/usingComponents.html) +</site-nav> +</variable> +</include> </div> - MarkBind has styles nested lists with additional padding and smaller text sizes up to **4** nesting levels. -Beyond that, you'd have to include your own styles! - -More than one siteNav file can be in `_markbind/navigation/` directory but a page may not have more than one siteNav. - -A siteNav has a fixed width of `300` pixels for its contents. A siteNav is [_responsive_](https://www.w3schools.com/html/html_responsive.asp) in that it will collapse to a menu button when the screen width is smaller than `992` pixels. It will then be completely hidden when the screen size is smaller than `576` pixels. - -If you wish to use a Layout but exclude its navigation file, specify `siteNav: none` in the `<frontmatter>` of the page. +Beyond that, you'd have to include your own styles. - -#### Expanding menu items by default +****Expanding menu items by default**** You can **append the `:expanded:` to a <tooltip content="a menu item with sub menu-items">parent menu item</tooltip> to make it expand by default.** In the example above, `* Docs :expanded:` will make the menu item `Docs` expand by default. A parent menu item that is also linked will not be collapsible %%e.g., the `Search` menu item in the above example%%. -#### Additional content in site navs - -You may have additional HTML and Markdown content in a <tooltip content="the file containing the code for a site navigation menu, e.g., `mySiteNav.md` in the example above">siteNav file</tooltip>, in which case the code for the siteNav should be enclosed in a `<navigation>` tag. There should only be one `<navigation>` tag in the file. - -<div class="indented"> - -{{ icon_example }} To include a heading for the site nav, - -```{.no-line-numbers} -# Site Map - -<navigation> -* [:house: Home]({{ baseUrl }}/index.html) -* --- -* Docs -... -</navigation> -``` - </div> -You can also include additional content between navigation items, such as [horizontal dividers.]({{ baseUrl }}/userGuide/readerFacingFeatures.html#horizontal-rules) -Just be sure to include it as a list item as well! - -<div class="indented"> - -{{ icon_example }} Inserting a horizontal divider: - -``` -* [:house: Home]({{ baseUrl }}/index.html) -* --- -* Docs -... -``` - -</div> - -<span id="short" class="d-none"> - -```{.no-line-numbers} -# Site Map -<navigation> -* [:house: Home]({{ baseUrl }}/index.html) -* Docs :expanded: - * [User Guide]({{ baseUrl }}/ug.html) - * [Dev Guide]({{ baseUrl }}/dg.html) -* [Search]({{ baseUrl }}/search.html) -</navigation> -``` - -```html -<frontmatter> - siteNav: mySiteNav.md -</frontmatter> -... -``` -</span> - -<span id="examples" class="d-none"> - -You can see an example of a Page Navigation Bar ==on the left side== of <a target="_blank" href="{{ baseUrl }}/userGuide/formattingContents.html">this page</a>. - -</span> +<div id="examples"></div> diff --git a/docs/userGuide/syntaxCheatSheet.md b/docs/userGuide/syntaxCheatSheet.md index 3fc54dbbd0..9a723f65d8 100644 --- a/docs/userGuide/syntaxCheatSheet.md +++ b/docs/userGuide/syntaxCheatSheet.md @@ -1,6 +1,6 @@ <frontmatter> title: "User Guide: Syntax Cheat Sheet" - layout: userGuide + layout: userGuide.md </frontmatter> # Syntax Cheat Sheet diff --git a/docs/userGuide/templates.md b/docs/userGuide/templates.md index 763155408c..46d8370559 100644 --- a/docs/userGuide/templates.md +++ b/docs/userGuide/templates.md @@ -3,7 +3,7 @@ <frontmatter> title: "User Guide: {{ title }}" - layout: userGuide + layout: userGuide.md </frontmatter> # Templates diff --git a/docs/userGuide/themes.md b/docs/userGuide/themes.md index 7240fc8df9..fcd424e756 100644 --- a/docs/userGuide/themes.md +++ b/docs/userGuide/themes.md @@ -4,7 +4,7 @@ <frontmatter> title: "User Guide: {{ title }}" - layout: userGuide + layout: userGuide.md </frontmatter> <span id="link" class="d-none"> diff --git a/docs/userGuide/tipsAndTricks.md b/docs/userGuide/tipsAndTricks.md index 3c69945c27..0f488a75bc 100644 --- a/docs/userGuide/tipsAndTricks.md +++ b/docs/userGuide/tipsAndTricks.md @@ -3,7 +3,7 @@ <frontmatter> title: "User Guide: {{ title | safe }}" - layout: userGuide + layout: userGuide.md </frontmatter> # {{ title | safe }} diff --git a/docs/userGuide/tweakingThePageStructure.md b/docs/userGuide/tweakingThePageStructure.md index 0807930537..a1951accd5 100644 --- a/docs/userGuide/tweakingThePageStructure.md +++ b/docs/userGuide/tweakingThePageStructure.md @@ -4,8 +4,8 @@ <frontmatter> title: "User Guide: {{ title }}" - layout: userGuide - pageNav: 2 + layout: userGuide.md + pageNav: 3 </frontmatter> <span id="link" class="d-none"> @@ -20,31 +20,171 @@ <hr><!-- ======================================================================================================= --> -<include src="syntax/pageHead.mbdf" /> +## Layouts + +MarkBind layouts can be used to provide structure and content around pages easily. + +To add a layout, first add any source file to the `_markbind/layouts` folder. Then, specify the layout the page will use using one of the following: +- the [`layout` property](siteJsonFile.md) of your site configuration file +- the [`layout` property](#front-matter) of the page front matter. + +<box type="info" seamless> + +If no layout is specified, the page defaults to the default layout (`default.md`). + +When using `markbind init`, a default layout is provided in the `_markbind/layouts` folder. +</box> + +Next, edit the layout file to your liking, and add the `{% raw %}{{ content }}{% endraw %}` variable where you want the page content to be rendered. + +<div id="layout-code-snippet"> + + +```html {.no-line-numbers highlight-lines="{{ highlightLines or "1-4,7,31,36-44[:],49,54,67-71" }}"} +{% raw %}<head-bottom> + <!-- Use head-top and head-bottom tags to insert content into the html <head> tag --> + <link rel="stylesheet" href="{{baseUrl}}/css/main.css"> +</head-bottom> + +<!-- Fix the header to the top while scrolling using the fixed attribute in a <header> tag --> +<header fixed> + <navbar type="dark"> + <a slot="brand" href="{{baseUrl}}/index.html" title="Home" class="navbar-brand"> + <img src="{{baseUrl}}/images/logo-darkbackground.png" height="20"> + </a> + <li> + <a highlight-on="exact" href="{{baseUrl}}/index.html" class="nav-link">HOME</a> + </li> + <li tags="environment--ug"> + <a highlight-on="sibling-or-child" href="{{baseUrl}}/userGuide/index.html" class="nav-link">USER GUIDE</a> + </li> + <li tags="environment--dg"> + <a highlight-on="sibling-or-child" href="{{baseUrl}}/devGuide/index.html" class="nav-link">DEVELOPER GUIDE</a> + </li> + <li slot="right"> + <form class="navbar-form"> + <searchbar :data="searchData" placeholder="Search" :on-hit="searchCallback" menu-align-right></searchbar> + </form> + </li> + </navbar> +</header> -<hr><!-- ======================================================================================================= --> +<div id="flex-body"> + <!-- Push content downward when using a fixed header with the fixed-header-padding class --> + <nav id="site-nav" class="fixed-header-padding"> + <div class="site-nav-top"> + <div class="font-weight-bold mb-2" style="font-size: 1.25rem;">User Guide</div> + </div> + <div class="nav-component slim-scroll"> + <site-nav> +* [**Getting Started**]({{baseUrl}}/userGuide/gettingStarted.html) + * **Authoring Contents** :expanded: + * [Overview]({{baseUrl}}/userGuide/authoringContents.html) + * [Adding Pages]({{baseUrl}}/userGuide/addingPages.html) + * [MarkBind Syntax Overview]({{baseUrl}}/userGuide/markBindSyntaxOverview.html) + * [Formatting Contents]({{baseUrl}}/userGuide/formattingContents.html) + * [Using Components]({{baseUrl}}/userGuide/usingComponents.html) + </site-nav> + </div> + </nav> + <div id="content-wrapper" class="fixed-header-padding"> + <!-- Insert the page's content into the layout using the {{ content }} variable --> + {{ content }} + </div> + <nav id="page-nav" class="fixed-header-padding"> + <div class="nav-component slim-scroll"> + <!-- Insert a page navigation menu using the {{ pageNav }} variable --> + {{ pageNav }} + </div> + </nav> +</div> -<include src="syntax/headers.mbdf" /> +<footer> + <div class="text-center"> + <small>[Generated by {{MarkBind}} on {{timestamp}}]</small><br> + <small>This site is powered by <a href="https://www.netlify.com/">Netlify</a>.</small> + </div> +</footer>{% endraw %} -<hr><!-- ======================================================================================================= --> +<!-- Insert content after the html <body> tag using the <script-bottom> tag --> +<script-bottom> + <script> + alert('Hi!') + </script> +</script-bottom> +``` -<include src="syntax/footers.mbdf" /> +</div> -<hr><!-- ======================================================================================================= --> +The rest of this section explains the other convenient features MarkBind provides in its layouts system, and references +the above code snippet. -<include src="syntax/siteNavigationMenus.mbdf" /> +<br> -<hr><!-- ======================================================================================================= --> +### Inserting content into the `<head>` -<include src="syntax/pageNavigationMenus.mbdf" /> +**You can insert code into the `<head>` section of the generated HTML page**, for example, to add links to custom JavaScript or CSS files. -<hr><!-- ======================================================================================================= --> +You may do so by inserting the html `<head>` content into `<head-top>` and `<head-bottom>` tags in the layout file, which are inserted at the top and bottom (after MarkBind's assets) of the `<head>` tag respectively. + +The above example shows the use of the `<head-bottom>` tag to insert a custom stylesheet (`main.css`). + +--- + +### Inserting scripts after the `<body>` tag + +**You may also insert html code after the `<body>` section of the generated HTML page**. This is useful for including custom scripts. +Simply insert the code / `<script>` tags into a `<script-bottom>` tag. + +The above example shows the use of the `<script-bottom>` tag to show a browser alert box with the message **'Hi!'**. + +<box type=info seamless> + +The scripts inserted here are processed last, after all of MarkBind's processing. + +If you wish insert scripts at the bottom, before MarkBind's scripts, simply insert them into the bottom of the layout file. + +</box> + +--- + +### Fixing the header to the top + +Headers are commonly included inside the html `<header>` tag. In encouraging this, a convenient interface to implement <tooltip content="Headers that stick to the top of the page while scrolling the content">fixed headers</tooltip> surrounding the `<header>` tag is provided that ensures page anchors work correctly. + +****To fix the `<header>`**** +1. Add the `fixed` attribute to your `<header>` element in the layout per the above example. + +2. Then, to add the necessary top padding for the main content, add the `fixed-header-padding` class to **elements that should be shifted down** in accordance with the fixed header. + +<box type="tip" seamless> + +If you are not sure where to put the `fixed-header-padding` attribute, you may also refer to the default template for `markbind init`, which already has this setup. +</box> + +--- + +### Constructing a site navigation menu easily + +<br> + +<include src="syntax/siteNavigationMenus.mbdf#content" /> + +--- + +### Constructing a page navigation menu + +<br> -<include src="syntax/pageLayouts.mbdf" /> +<include src="syntax/pageNavigationMenus.mbdf#content"> +<variable name="doNotShowPageNav">true</variable> +</include> <hr><!-- ======================================================================================================= --> -<include src="plugins/tags.mbdf" /> +<include src="plugins/tags.mbdf"> +<variable name="topHeadingLevel">##</variable> +</include> {% from "njk/common.njk" import previous_next %} {{ previous_next('usingPlugins', 'reusingContents') }} diff --git a/docs/userGuide/usingComponents.md b/docs/userGuide/usingComponents.md index ad2e038b34..d1c9815e35 100644 --- a/docs/userGuide/usingComponents.md +++ b/docs/userGuide/usingComponents.md @@ -4,7 +4,7 @@ <frontmatter> title: "User Guide: {{ title }}" - layout: userGuide + layout: userGuide.md pageNav: 3 </frontmatter> diff --git a/docs/userGuide/usingHtmlJavaScriptCss.md b/docs/userGuide/usingHtmlJavaScriptCss.md index ce5f65082c..286ebc1e75 100644 --- a/docs/userGuide/usingHtmlJavaScriptCss.md +++ b/docs/userGuide/usingHtmlJavaScriptCss.md @@ -4,7 +4,7 @@ <frontmatter> title: "User Guide: {{ title }}" - layout: userGuide + layout: userGuide.md </frontmatter> <span id="link" class="d-none"> diff --git a/docs/userGuide/usingPlugins.md b/docs/userGuide/usingPlugins.md index 6d38b4dcd5..d95e02442d 100644 --- a/docs/userGuide/usingPlugins.md +++ b/docs/userGuide/usingPlugins.md @@ -4,7 +4,7 @@ <frontmatter> title: "User Guide: {{ title }}" - layout: userGuide + layout: userGuide.md pageNav: "default" </frontmatter> diff --git a/docs/userGuide/workingWithSites.md b/docs/userGuide/workingWithSites.md index 7349cbb538..f82cfbc13f 100644 --- a/docs/userGuide/workingWithSites.md +++ b/docs/userGuide/workingWithSites.md @@ -3,7 +3,7 @@ <frontmatter> title: "User Guide: {{ title }}" - layout: userGuide + layout: userGuide.md </frontmatter> # {{ title }}