Link Search Menu Expand Document

Activity 1.1: Fork & Commit

  1. Open your browser and log into

  2. Navigate to or search for the futureDocs repository.

  3. Fork this repository and go to your fork, if your browser doesn’t automatically switch you to it.

  4. Go to your Fork’s repository settings, and then to GitHub Pages settings. Click on the drop down menu below “Source” and select ‘gh-pages’.

  5. Here you should see your site link as well - Ctrl+click the URL to view your site in a new tab (or reload if you’ve already got it open).

  6. Open GitHub Desktop, and clone this repo to your local system:
    • File > Clone: Your list of owned repositories should appear, but if not, head back over to the front page of the repo in the browser and copy/paste the URL then use that. Once back in GitHub Desktop and you’ve cloned the repo, be sure you’re in the gh-pages branch.
  7. Note: The local destination for this repo will be in your Documents folder, within a GitHub folder (yourusername/Documents/Github/futureDocs) by default, unless you’ve updated your destination preferences in GitHub Desktop.

  8. Open your project in VSCode. Your repository will be visible in the explorer, and you should see the following:
├── _site
├── assets
├── Gemfile.lock
├── Gemfile
├── LICENSE.txt
├── 404.html
├── package-lock.json
├── package.json
├── _config.yml
├── about.markdown
├── about.markdown
├── index.markdown
  1. Select the file in your explorer and go ahead and edit your README.
    # Hello Docs!
  2. Save your changes. In GitHub Desktop, you should now see the change you made being tracked. Write a commit message and commit this change.

  3. Push this change to the remote version with the Push button in the upper right corner of GH Desktop.

  4. In your browser, on the landing page of your fork’s repository on, you should now see your updated README.

Congrats! You just committed a change!

Activity 1.2: System Check

Now that you’ve updated your README, let’s check to make sure your fork’s jekyll site is up and running.

  1. In your VSCode terminal, your working directory should already be the repository, because VSCode is smart. From here, run:
    bundle install
  2. Running the following will build your site locally
    bundle exec jekyll serve
  3. Navigate to http://localhost:4000/ in your browser. You should see a site there.

  4. To stop serving

A Word About Testing and making Commits

The essential process for editing pages will go as follows:

  • edit
  • save
  • serve locally (and edit more if need be)
  • commit
  • push
  • check published site

When you’re updating documentation, it’s best to group commits around related changes, rather than changing lots of different things all at once in a single commit. This makes it easier to roll back specific changes without having to re-do tons of other work.

You might start off with a big import of complete docs, but from there it’s a good idea to be systematic about updates.