Create new lab

Creating a new lab follows the same process as under Add content:

  1. Prepare your Git branch
  2. Make changes
  3. Commit and push your changes
  4. Create Pull request
  5. Clean up branches locally and remotely (Github)

The only difference is in the first time you execute step "2. Make changes", so follow this process:

  • Follow step "1. Prepare your Git branch" under Add content.
  • Come back here and run the below "Make first changes for new lab".
  • Go back to Add content and run from step 3.
    (You are done here :-)

Make first changes for new lab

The following steps are used to crate a new lab based on the provided template

1. Replicate Template to your lab

Select the template_1.0 folder Select template folder

Make a copy of the template_1.0 folder Copy template folder

Rename the template_1.0 copy folder to < product >_< version > for wich this new lab is intended,
e.g. mvi_saas Rename template folder

Also rename the folder under img/template_1.0 using the same name lab name,
e.g. img/mvi_saas. Rename img/template folder

Save the file.

Important

It is important that this structure is kept consistent cross all labs in order to easily build and deploy the complete set of labs.

2. Modify the mkdocs.yml file

The mkdocs.ymlfile holds the configuration of the new lab, i.e. some generic information about the new lab, like location of where the site will be created during the build and also which .md (markdown) files it consist of based on the navigation information.

Select and open the mkdocs.yml file located in the root of you new lab folder Select mkdocs.yml

Edit the marked areas suitable for your new lab Edit mkdocs.yml

Which could look like this Edit mkdocs.yml

Save the file.

Note

The nav: definition holds the navigation menu for the new lab.
It is only the index.md and about.md that need to have some mandatory information, as explained below. The rest of the markdown files and navigation menu is defined by the way the lab is structured and how many exercises it consist of.

3. Modify the index.md file

The index.md file is the landing / welcome page for the new lab.

Select and open the index.md file located in the docs folder of you new lab Select index.md

Edit the file and make sure to change the marked areas suitable for your new lab Edit index.md

Which could look like this Edit index.md

Save the file.

Remember to do this:

Update the Updated at the end of this file to current date once the new lab is ready.

4. Modify the about.md file

The about.md file contains a list of the contributors to this lab as well as the Change Information.

Select and open the about.md file located in the docs folder of you new lab Select about.md

Edit the file and make sure to change the marked areas suitable for your new lab Edit about.md

Which could look like this Edit about.md

Save the file.

Remember to do this:

Update both sections when the lab is ready.

5. Add the new lab to the build script

First we need to update the build_all_mkdocs.sh file located in the root of the monitor-hands-on-lab folder. This file contains the shell script for building the entire IBM Maximo Labs static web site.

Select and open the build_all_mkdocs.sh file Select build_all_mkdocs.sh

Scroll down to find # Build the template level: Edit build_all_mkdocs.sh

Copy the section and paste it above the #### DON't CHANGE THE BELOW MANDATORY... line. Change the comment and the lab= variable to match the folder of the new lab. Edit build_all_mkdocs.sh

Save the file.

Attention

Please don't change anything else!

6. Build and verify your lab content

In a terminal navigate to the root of this git repo and execute the build script:

./build_all_mkdocs.sh

It could look like this: Edit build_all_mkdocs.sh

Wait until it has finished building the whole site. Edit build_all_mkdocs.sh

Open a browser and navigate to http://localhost:8080/ in order to verify that the build was successful.
Edit build_all_mkdocs.sh

If the new lab has not yet been added to the index.md in the toplevel page, then navigate directly to the new lab http://localhost:8080/mvi_saas in order to verify that your changes look as expected.
Edit build_all_mkdocs.sh

Tip

Press control-c to stop the web server and get back to the prompt.

Congratulations, you have now created the foundation for the new lab following the structure and consistensy of the entire IBM Maximo Labs site.

Now you "only" need to add all the content to the foundation, by adding markdown files and images according to the structure.

Remember to do this:

Go back to Add content and run from step 3. (You are done here :-)

Note

It is good practise to commit your changes once the foundation is in place - and again when you have created or updated every markdown files in the exercise.