Learn

Overview

Before proceeding you should first read and understand the About page.

Here are the steps and instruction to create your own SOIL module:

  1. Create a domain or sub-domain for your module;
  2. Create a Git repository to contain your module;
  3. Clone that repository locally for editing;
  4. Populate the local repo with SOIL module boilerplate starter files;
  5. Customize the starter files to match your information;
  6. Add your own new content while testing locally; 💬
  7. Commit and push your local repository to your Git service;
  8. Deploy your Git repository on Netlify;
  9. Confirm your deployment and test content online.

💬 If you have no idea what this means then talk to your friendly neighborhood instructional technologist to help you out or just set it up. Then you can simply focus on adding your content.

Create Domain

VuePress sites are easier to work with if you have a domain or sub-domain. It is just easier when dealing with link references in the content. It also provides a better chance for your users to pull it up with a few keystrokes in their web browser. This is especially nice if they do not have progressive web application support that will prompt them to add your SOIL module as an app to their home screen.

Go ahead and create a domain or sub-domain for your SOIL module. You will not need it right away but it can take time to go through so get that started now. It is nice to cluster several modules into one parent module (see Modularity) that has a single main subdomain URL for example:

  • soilsrc.org
  • baseml.soilsrc.org
  • vuepress.soilsrc.org

💬 If you have the option we recommend managing your DNS with Netlify but not every content creator will have that option.

Create Repository

SOIL module knowledge source must be contained in a Git repository. Learning to create a repository is beyond the scope of this module but you will need to do it before continuing. Refer to the services linked in the first sentence to learn how to create a repo for each. You will first need an account on that service and preferably have setup SSH keys allowing easier connections.

If you want you can simply fork this repo and use your forked copy instead of creating something new. Then you can just change stuff. The downside is that you are initially locked into using GitHub and your source will show it as being a fork of the boilerplate.

💬 It's a good idea to name your repository the same as the name of the domain or sub-domain you are going to use.

Clone Locally

Once you have created the repository for your SOIL module go ahead and clone it locally. Assuming you do the cloning from a Bash command line (as you should) it would look something like the following:

cd ~
mkdir repos
cd repos
git clone git@github.com:soilsrc.org/vuepress

Ignore any warnings about the repo being empty.

💬 Setting up Git and configuring Bash is beyond the scope of this module and listed as a prerequisite in the Introduction.

Add Boilerplate

Boilerplate is a term referring to anything you can copy to get started faster. Some people call them templates.

There are many ways to get this boilerplate starter content all with different implications:

  • Forking;
  • Downloading;
  • Copying.

Forking

Forking was suggested as an option when creating the repository. If you did that then you don't need to add boilerplate.

💬 This is only recommended for those wanting to get a quick feel for how things work. The left over fork relationship is clunky, ugly, and unnecessary.

Downloading

One option is to simply download the zip file and expand it. Make sure you are in your newly cloned repo directory and then run the following, which you can simply cut and paste onto your command line:

wget https://github.com/soilsrc/vuepress/archive/master.zip
unzip master.zip
mv vuepress-master/* .
mv vuepress-master/.gitignore .
rmdir vuepress-master

There are many more elegant ways of doing the above. Obviously you would change the above to match your case.

You can also download the zip file using your web browser and just open it from your desktop if you prefer to move the files using your graphic file explorer:

ZIP Download

💬 This is the best option for those who just want the content and don't want any connection to the boilerplate remaining.

Copying

The slowest way would be to simply open each of the files from the GitHub source and copy them into files where they belong. There really are not that many of them so this option might be easiest for many. Just look at every file in the boilerplate and recreate it one by one in your own empty cloned repository.

💬 This is by far the best option when first starting out so that you can understand what is in every file and why it is there.

Change Config

The config.js file contains most of the VuePress config properties needed. The only changes you need to make are as follows:

  1. Change the title
  2. Set your Google Analytics ID (if you have one)
  3. Change themeConfig.repo to yours
  4. Note the themeConfig.nav settings for later update

Title

  title: 'SOIL • VuePress • Netlify',

Keep the title to under 10 characters if you can. If you don't it will wrap when made very thin.

Title Prob

You can have a little Stylus/CSS experience you can also make this look better by editing the /docs/.vuepress/theme/Navbar.vue file.

Google

  ga: 'UA-555555555-1',

One of the best part of using VuePress is that you simply need to plugin your Google Analytics ID to turn on usage tracking.

Repo

    repo: 'soilsrc/vuepress', 

Change this to your GitHub organization/user and repository name. If you use anything else use the full path to it.

    nav: [
      { text: 'Introduction', link: '/intro/' },
      { text: 'Learn', link: '/learn/' },
    ],

By default there are only these two navigational menus. Add yours here as you go. If you need sub menus that is also an option.

Change Splash

The splash screen is the first page most people will see and becomes the home screen for your app for those that support Progressive Web Apps.

To change the text alter the text in the docs/.vuepress/README.md Keep in mind that you cannot put HTML or BaseML Markdown currently in these.

You can also optionally add some BaseML after the front-matter if you want something to appear on the home splash page.

⚠️ Do not put a SOIL fence on the splash page.

Replace Images

The following images can just be replaced with images that have the same names:

  • docs/.vuepress/public/hero.png
  • docs/.vuepress/public/logo.png
  • docs/.vuepress/public/logo192.png
  • docs/.vuepress/public/logo512.png

The 192 and 512 versions are for when your SOIL module is saved as a progressive web app.

You can usually get away with copying the logo192.png to logo.png which becomes the icon used to bookmark your page, but only if it is a square. Otherwise it will be resized when displayed as the bookmark icon (favicon).

Add Content

Commit and Push

Deploy

Confirm and Test

Last Updated: 10/19/2018, 8:21:48 PM