Explore MarkBind as a User

Explore MarkBind as a User

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, 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.

Setting up MarkBind

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!

1. Create a new folder called at a location outside of the MarkBind source code directory.
2. Go to the folder and run markbind init to create a new MarkBind site with the default template.
3. 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.

    

    


    
    

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 - Covering Markdown & Markdown-like syntax.
• Using Components - Covering MarkBind components (Built with Vue.js or Native HTML).

Creating Content

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!

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

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:

• Frontmatter
• Layouts
• site.json

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

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

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

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

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.json section for more details.

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

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.

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

4. 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
   
       
   
       
   
   
       
       

5. Commit and push the changes to the main branch with the following commands:

   git add .
   git commit -m "Update content"
   git push origin main
   
       
   
       
   
   
       
       

6. 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).

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
• Try out MarkBind's 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

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