{% set title = "Explore MarkBind as a User" %} {{ title }}

title: "{{ title }}" layout: devGuide.md pageNav: 3

Getting to know MarkBind as a user will help you understand what MarkBind offers and how it can be used to create static websites. This will also help you understand the different components and syntax available in MarkBind, which will be useful when you want to debug issues or create similar features in the future.

TLDR

Setup the master branch MarkBind
Create a MarkBind site
Create content with MarkBind
Modify site structure and configuration
Deploy your MarkBind site

Setup the master branch of MarkBind

As mentioned in our user guide user guide, we can either install MarkBind via npm or create a new MarkBind site with npx.

In this bootcamp, we want to set up the master branch MarkBind so that we can test out any changes we make to the codebase on our local machine.

You can also switch between the master branch MarkBind and check out other branches if you are working on multiple issues. This is also useful when you want to test out a PR submitted by another developer.

Checkpoint

After setting up MarkBind, try running from the root directory of your MarkBind repository:

markbind -v to check that you have the correct version of MarkBind installed
cd docs && markbind serve -d to check that you can serve the MarkBind documentation site in development mode

If you can browse the MarkBind documentation site that should have automatically been up in your browser at http://localhost:8080, you have successfully set up MarkBind!

If port 8080 is in use, another port will be chosen. Refer to the console output for the exact URL address.

$ markbind -v
  __  __                  _      ____    _               _ 
 |  \/  |   __ _   _ __  | | __ | __ )  (_)  _ __     __| |
 | |\/| |  / _` | | '__| | |/ / |  _ \  | | | '_ \   / _` |
 | |  | | | (_| | | |    |   <  | |_) | | | | | | | | (_| |
 |_|  |_|  \__,_| |_|    |_|\_\ |____/  |_| |_| |_|  \__,_|

 v4.0.2
Usage: markbind <command>

Options:
  -V, --version                      output the version number      
  -h, --help                         display help for command       

Commands:
  init|i [options] [root]            init a markbind website project
  serve|s [options] [root]           build then serve a website from a directory
  build|b [options] [root] [output]  build a website
  deploy|d [options] [root]          deploy the latest build of the site to the repo's Github pages
  help [command]                     display help for command

$ cd docs && markbind serve -d
  __  __                  _      ____    _               _
 |  \/  |   __ _   _ __  | | __ | __ )  (_)  _ __     __| |
 | |\/| |  / _` | | '__| | |/ / |  _ \  | | | '_ \   / _` |
 | |  | | | (_| | | |    |   <  | |_) | | | | | | | | (_| |
 |_|  |_|  \__,_| |_|    |_|\_\ |____/  |_| |_| |_|  \__,_|

 v4.0.2
info: Changes detected in MarkBind Vue Source Files:
Bundle is regenerated by webpack and built pages are re-rendered with the latest bundle.
info: Website generation started at 4:16:47 pm
info: Building assets...
info: Assets built
info: Generating pages...
[=======================------------------------------------] 23 / 59 pages [========================-------[======[===[===========================================================] 59 / 59 pages built
info: Pages built
webpack built 6d52f45b1910f9f545a2 in 11017ms
i ｢wdm｣: Hash: 6d52f45b1910f9f545a2
Version: webpack 4.46.0
Time: 11017ms
Built at: 01/01/2023 4:16:58 pm
                                Asset      Size    Chunks             Chunk Names
          fonts/KaTeX_AMS-Regular.ttf  62.1 KiB            [emitted]
         fonts/KaTeX_AMS-Regular.woff  32.7 KiB            [emitted]
        fonts/KaTeX_AMS-Regular.woff2  27.4 KiB            [emitted]
     fonts/KaTeX_Caligraphic-Bold.ttf  12.1 KiB            [emitted]
    fonts/KaTeX_Caligraphic-Bold.woff  7.54 KiB            [emitted]
   fonts/KaTeX_Caligraphic-Bold.woff2  6.75 KiB            [emitted]
  fonts/KaTeX_Caligraphic-Regular.ttf  12.1 KiB            [emitted]
 fonts/KaTeX_Caligraphic-Regular.woff  7.48 KiB            [emitted]
fonts/KaTeX_Caligraphic-Regular.woff2  6.75 KiB            [emitted]
         fonts/KaTeX_Fraktur-Bold.ttf  19.1 KiB            [emitted]
        fonts/KaTeX_Fraktur-Bold.woff    13 KiB            [emitted]
       fonts/KaTeX_Fraktur-Bold.woff2  11.1 KiB            [emitted]
      fonts/KaTeX_Fraktur-Regular.ttf  19.1 KiB            [emitted]
     fonts/KaTeX_Fraktur-Regular.woff  12.9 KiB            [emitted]
    fonts/KaTeX_Fraktur-Regular.woff2  11.1 KiB            [emitted]
            fonts/KaTeX_Main-Bold.ttf  50.1 KiB            [emitted]
           fonts/KaTeX_Main-Bold.woff  29.2 KiB            [emitted]
          fonts/KaTeX_Main-Bold.woff2  24.7 KiB            [emitted]
      fonts/KaTeX_Main-BoldItalic.ttf  32.2 KiB            [emitted]
     fonts/KaTeX_Main-BoldItalic.woff    19 KiB            [emitted]
    fonts/KaTeX_Main-BoldItalic.woff2  16.4 KiB            [emitted]
          fonts/KaTeX_Main-Italic.ttf  32.8 KiB            [emitted]
         fonts/KaTeX_Main-Italic.woff  19.2 KiB            [emitted]
        fonts/KaTeX_Main-Italic.woff2  16.6 KiB            [emitted]
         fonts/KaTeX_Main-Regular.ttf  52.3 KiB            [emitted]
        fonts/KaTeX_Main-Regular.woff  30.1 KiB            [emitted]
       fonts/KaTeX_Main-Regular.woff2  25.7 KiB            [emitted]
      fonts/KaTeX_Math-BoldItalic.ttf  30.5 KiB            [emitted]
     fonts/KaTeX_Math-BoldItalic.woff  18.2 KiB            [emitted]
    fonts/KaTeX_Math-BoldItalic.woff2    16 KiB            [emitted]
          fonts/KaTeX_Math-Italic.ttf  30.6 KiB            [emitted]
         fonts/KaTeX_Math-Italic.woff  18.3 KiB            [emitted]
        fonts/KaTeX_Math-Italic.woff2  16.1 KiB            [emitted]
       fonts/KaTeX_SansSerif-Bold.ttf  23.9 KiB            [emitted]
      fonts/KaTeX_SansSerif-Bold.woff  14.1 KiB            [emitted]
     fonts/KaTeX_SansSerif-Bold.woff2  11.9 KiB            [emitted]
     fonts/KaTeX_SansSerif-Italic.ttf  21.8 KiB            [emitted]
    fonts/KaTeX_SansSerif-Italic.woff  13.8 KiB            [emitted]
   fonts/KaTeX_SansSerif-Italic.woff2  11.7 KiB            [emitted]
    fonts/KaTeX_SansSerif-Regular.ttf    19 KiB            [emitted]
   fonts/KaTeX_SansSerif-Regular.woff    12 KiB            [emitted]
  fonts/KaTeX_SansSerif-Regular.woff2  10.1 KiB            [emitted]
       fonts/KaTeX_Script-Regular.ttf  16.3 KiB            [emitted]
      fonts/KaTeX_Script-Regular.woff  10.3 KiB            [emitted]
     fonts/KaTeX_Script-Regular.woff2  9.42 KiB            [emitted]
        fonts/KaTeX_Size1-Regular.ttf  11.9 KiB            [emitted]
       fonts/KaTeX_Size1-Regular.woff  6.34 KiB            [emitted]
      fonts/KaTeX_Size1-Regular.woff2  5.34 KiB            [emitted]
        fonts/KaTeX_Size2-Regular.ttf  11.2 KiB            [emitted]
       fonts/KaTeX_Size2-Regular.woff  6.04 KiB            [emitted]
      fonts/KaTeX_Size2-Regular.woff2  5.09 KiB            [emitted]
        fonts/KaTeX_Size3-Regular.ttf  7.41 KiB            [emitted]
       fonts/KaTeX_Size3-Regular.woff  4.32 KiB            [emitted]
      fonts/KaTeX_Size3-Regular.woff2  3.54 KiB            [emitted]
        fonts/KaTeX_Size4-Regular.ttf  10.1 KiB            [emitted]
       fonts/KaTeX_Size4-Regular.woff  5.84 KiB            [emitted]
      fonts/KaTeX_Size4-Regular.woff2  4.81 KiB            [emitted]
   fonts/KaTeX_Typewriter-Regular.ttf  26.9 KiB            [emitted]
  fonts/KaTeX_Typewriter-Regular.woff  15.7 KiB            [emitted]
 fonts/KaTeX_Typewriter-Regular.woff2  13.3 KiB            [emitted]
                   js/markbind.min.js   1.3 MiB  markbind  [emitted]  markbind
Entrypoint markbind = js/markbind.min.js
[0] multi webpack-hot-middleware/client ../packages/core-web/src/index.js 40 bytes {markbind} [built]
[../../node_modules/@babel/runtime/helpers/arrayWithHoles.js] ../node_modules/@babel/runtime/helpers/arrayWithHoles.js 
184 bytes {markbind} [built]
[../../node_modules/@babel/runtime/helpers/defineProperty.js] ../node_modules/@babel/runtime/helpers/defineProperty.js 
367 bytes {markbind} [built]
[../../node_modules/@babel/runtime/helpers/iterableToArrayLimit.js] ../node_modules/@babel/runtime/helpers/iterableToArrayLimit.js 711 bytes {markbind} [built]
[../../node_modules/@babel/runtime/helpers/nonIterableRest.js] ../node_modules/@babel/runtime/helpers/nonIterableRest.js 309 bytes {markbind} [built]
[../../node_modules/@babel/runtime/helpers/slicedToArray.js] ../node_modules/@babel/runtime/helpers/slicedToArray.js 522 bytes {markbind} [built]
[../../node_modules/strip-ansi/index.js] ../node_modules/strip-ansi/index.js 154 bytes {markbind} [built]
[../../node_modules/webpack-hot-middleware/client-overlay.js] ../node_modules/webpack-hot-middleware/client-overlay.js 2.14 KiB {markbind} [built]   
[../../node_modules/webpack-hot-middleware/client.js] ../node_modules/webpack-hot-middleware/client.js 7.69 KiB {markbind} [built]
[../../node_modules/webpack-hot-middleware/process-update.js] ../node_modules/webpack-hot-middleware/process-update.js 4.36 KiB {markbind} [built]   
[../../node_modules/webpack/buildin/module.js] ../node_modules/webpack/buildin/module.js 497 bytes {markbind} [built]
[./src/VueCommonAppFactory.js] ../packages/core-web/src/VueCommonAppFactory.js 1.09 KiB {markbind} [built]
[./src/index.js] ../packages/core-web/src/index.js 8.17 KiB {markbind} [built]
[./src/scrollTopButton.js] ../packages/core-web/src/scrollTopButton.js 1.49 KiB {markbind} [built]
[./src/styles/index.css] ../packages/core-web/src/styles/index.css 1.09 KiB {markbind} [built]
    + 346 hidden modules
i ｢wdm｣: Compiled successfully.
info: Site data built
info: Website generation complete! Total build time: 11.242s
info: Serving "C:\Users\User\Documents\GitHub\markbind\docs\_site" at http://127.0.0.1:8080
info: Press CTRL+C to stop ...

Create a MarkBind site

With MarkBind installed, we can now create a new MarkBind site.

We recommend that you set up a new repository for this MarkBind site so that you can push your site to GitHub pages later. This MarkBind site can be used to test out any changes you make to the codebase.

As an example, let's create a test site together!

You can refer to the example repository here for the code and here for the deployed site if you get stuck.

Create a new folder called "mb-dev-xxx" at a location outside of the MarkBind source code directory.
Go to the folder and run markbind init to create a new MarkBind site with the default template.
Initialize a new git repository in the folder by running git init. You can also create a new public repository on GitHub first and clone it to your local machine.

You should see the following output:

$ markbind init
  __  __                  _      ____    _               _
 |  \/  |   __ _   _ __  | | __ | __ )  (_)  _ __     __| |
 | |\/| |  / _` | | '__| | |/ / |  _ \  | | | '_ \   / _` |
 | |  | | | (_| | | |    |   <  | |_) | | | | | | | | (_| |
 |_|  |_|  \__,_| |_|    |_|\_\ |____/  |_| |_| |_|  \__,_|

 v4.0.2
info: Initialization success.

Checkpoint

After setting up the MarkBind test site, try running the following common operations from the root directory of your test site:

Build the site by running markbind build
Serve the site by running markbind serve
Serve the site in development mode by running markbind serve -d

You now have the test site up and running!

Create Content with MarkBind

MarkBind contains a range of additional syntax on top of Markdown. It also comes with a set of components that can be used to create content.

Two essential sections of the user guide to get started with are:

Formatting Contents Formatting Contents - Covering Markdown & Markdown-like syntax.
Using Components Using Components - Covering MarkBind components (Built with Vue.js or Native HTML).

The generated MarkBind site from the above step also includes a few sample usage in the index.md file.

Now, let's try editing the index.md file to add some content of our own!

Open the index.md file in your mb-dev-xxx folder.
Replace the wording Landing Page Title with MarkBind Developer Test Site.
Modify or add some content utilizing one or more of the following syntaxes:
- Text Styles Text Styles
- Code Block Code Block
- Emoji Emoji
- etc.
Modify or add some content utilizing one or more of the following components:
- Box Box
- Panel Panel
- Tooltip Tooltip
- etc.

Checkpoint

With live preview, you should be able to see the changes you have made to the site after saving. Check that the following are true:

Serve the site by running markbind serve -d
Make changes to the index.md file and save
See the changes reflected in the live preview, with the correct rendering of the syntax and components

You now have created content with MarkBind!

Modify Site Structure and Configuration

There are a few ways to modify the site's (as well as the page's) structure and configuration. We will cover the following:

Let's continue with the test site we created earlier and modify the index.md file via frontmatter.

Open the index.md file in your mb-dev-xxx folder.
Change the pageNavTitle in the frontmatter from Topics to Index Page.
Change the pageNav in the frontmatter from 4 to 5.

Checkpoint

Ensure that you are still serving the site with markbind serve -d. Check that the following are true:

The rendered page navigation title is changed to Index Page
The rendered page navigation content now shows H5 headings as well

Screenshot before the changes:

Screenshot after the changes:

Another commonly adjusted structure is the layout of the site (especially, the site's top header and the left-hand-side navigation).

Open the _markbind/layouts/default.md file in your mb-dev-xxx folder.
Change Your Logo to MarkBind Developer Test Site.
Change Home :house: to My Test Playground :computer:.

Checkpoint

Ensure that you are still serving the site with markbind serve -d. Check that the following are true:

The rendered page logo in the header is changed to MarkBind Developer Test Site
The rendered site navigation title is changed to My Test Playground 💻

Screenshot after the changes:

Lastly, let's modify the site configuration to change the site title and more.

The site.json file is autogenerated and located in the root directory of the site. Refer to the User Guide - site.jsonsite.json section for more details.

Open the site.json file in your mb-dev-xxx folder.
Change "titlePrefix": "", to "titlePrefix": "mb-dev-xxx",.
Under pages, add "title": "Home".

Checkpoint

Ensure that you are still serving the site with markbind serve -d. Check that the following are true:

The page title in the browser tab is changed to mb-dev-xxx - Home

Screenshot after the changes:

You now have modified some of the commonly adjusted site structure and configuration!

Deploy your MarkBind site

MarkBind sites can be easily deployed with CLI commands or via CI. Let's try deploying our site via GitHub Actions.

Open the site.json file in your mb-dev-xxx folder.
Change "baseUrl": "", to "baseUrl": "/mb-dev-xxx", (Note the leading / and that the value is the same as your GitHub repository name).
Create a .github/workflows/deploy.yml file with the following content mentioned in the GitHub Actions guideGitHub Actions guide.
1. Note that you should change branches: master to branches: main if you are using the main branch.

Update you GitHub repository settings to enable read and write permissions for Actions.
1. Navigate to the Settings > Actions section.
2. Under General tab, find the Workflow permissions section.
3. Click to toggle to Read and write permissions.
4. Save by clicking on the Save button.
Ensure that you have added your remote GitHub repository to your local repository with the following command (replace xxx with your GitHub username):
```
git remote add origin https://github.com/xxx/mb-dev-xxx.git
```
Commit and push the changes to the main branch with the following commands:
```
git add .
git commit -m "Update content"
git push origin main
```
Update your GitHub repository setting for deploying to GitHub Pages.
1. Navigate to the Settings > Pages section on GitHub for that repository and set the source to Deploy from a branch and the branch to gh-pages and /(root).

Checkpoint

Check that the following are true:

The triggered GitHub action runs are successful
The site is deployed and available at https://<username>.github.io/mb-dev-xxx/ (after a few seconds to a few minutes)

Congratulations! 🎉🎉🎉 You have deployed your MarkBind site!

Summary

In the first part of this bootcamp, we experimented with MarkBind as a user. We have set up the master branch of MarkBind and created a new MarkBind site. We have also created content with MarkBind components/syntax and deployed our site.

Here are some additional tasks for you to try out:

Create a new MarkBind site with a different theme theme
Try out MarkBind's include mechanism include mechanism
Create a dedicated MarkBind site for your personal usage and share it with us
- You can see some examples in the [MarkBind showcase]({{ baseUrl }}/showcase.html)

Take a break now ☕ and we will continue with the second part of the bootcamp!

{% from "njk/common.njk" import previous_next %} {{ previous_next('intro', 'contributeToDocs') }}

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

{{ title }}

TLDR

Setup the master branch of MarkBind

Create a MarkBind site

Create Content with MarkBind

Modify Site Structure and Configuration

Deploy your MarkBind site

Summary

FilesExpand file tree

exploreMarkBind.md

Latest commit

History

exploreMarkBind.md

File metadata and controls

{{ title }}

TLDR

Setup the master branch of MarkBind

Create a MarkBind site

Create Content with MarkBind

Modify Site Structure and Configuration

Deploy your MarkBind site

Summary