Advanced Documentation Editing

Using VSCode to make edits to these docs

🗏 View page source ✐ Edit this page ✎ Create child page

Using VSCode - Experts Only!

Alright, you are a cool hacker elite and want to edit the site the advanced way? You can clone the whole repo and use Visual Studio Code to manage source control and make edits.

Honestly, it is a bit much if all you wanna do is edit a page now and again, but if you are doing heavy editing this is the way to go. Take a look at the comparison:

GitHub Editor VSCode
Basic Editor Full IDE
Commit files one by one Commit all when ready
Slow image upload process Copy paste images directly
Inaccurate slow previews Automatic accurate preview
Browser based Must install software (free)
Easy authentication One time auth setup

“Quick” Setup

  1. Make sure you have a GitHub account / linked to our private repo
  2. Download and install VSCode (what you’ll write in)
  3. Download Hugo (used for previewing the site!)
    1. Scroll down and click on your os (prob hugo_extended_versionnumber_windows-amd64.zip)
    2. Extract the contents of the zip somewhere - I made a lil folder next to where I want to store the website files themselves.
    3. Annoyingly, you’ll have to manually set the “PATH” environment variable so VS can talk to Hugo:
      1. Type “Edit the system environment variables” into the start menu - should pop up quick.
      2. Click the old school Environment Variables button near the bottom of the dialog box.
      3. Click on Path under System variables, then click Edit...
      4. Click New, then type the full path to the directory you extracted Hugo into. You can cheat by clicking on the path in explorer and copy pasting it. Should look something like C:\Users\johnt\OneDrive\Documents\WebDev\Hugo
  4. Download and install Git. This allows VScode to connect to GitHub.
  5. Open up VSCode. It will probably bombard you with co-pilot garbage.

OPTIONAL: If you want spell check in VSCode click on the Extensions icon (bottom on the left menu) and type “Code Spell Checker” and install. Hotkey to fix is a bit weird ctrl+.

Cloning the Repo

Almost done! Now all you need to do is clone the repo from GitHub. VScode makes this pretty simple:

{{0xc000cbbe00 0xc000cbbe00 image.png alt text alt text 0xc000803d40} 0 false}
Click on the third icon on the right (looks like 3 dots connected…?) This is the source control panel. From there, click Clone Repository On the top bar it will ask you to put in a GitHub URL. Enter the following then hit enter: https://github.com/whitelotusinteractive/wli-docs

First it will ask you where you want to save the repo. It will automatically place a folder named “wli-docs” wherever you choose.

{{0xc000cbbe00 0xc000cbbe00 image-1.png alt text alt text 0xc000a836e0} 1 false}
You’ll next get a popup asking for authentication. Click Sign in with your browser - if you were already signed into GitHub it will pop a success page in your browser.
{{0xc000cbbe00 0xc000cbbe00 image-2.png alt text alt text 0xc0007e03c0} 2 false}
Back in VSCode, another popup message should appear. Check the “I trust ya” checkbox then click Yes, I trust the authors.

{{0xc000cbbe00 0xc000cbbe00 image-3.png alt text alt text 0xc00075c120} 3 false}
Now if you click on the top left icon (explorer) you should see the repo! You are ready to work.

Hugo

Hugo is used to “render” the website, and has lots of nifty features. Fortunately, you shouldn’t need to worry about any of that since I already wrote the bulk of the code - however, you do want Hugo installed so you can preview your work.

{{0xc000cbbe00 0xc000cbbe00 image-4.png alt text alt text 0xc0009b2480} 4 false}

You’ll need to open a terminal from within VSCode - from the top menu bar, select Terminal > New Terminal.

Now, in the terminal the opened up at the bottom of the window, type hugo serve. Assuming your environment variables were setup correctly, it will run hugo and locally host the website on your computer. Near the bottom of the terminal output it should say something like Web Server is available at //localhost:1313/ (bind address 127.0.0.1)

If it complains about Hugo not existing, try restarting VSCode, then restarting comp, assuming you did indeed follow the hugo installation correctly.

OK, now all you need to do is copy past that //localhost:1313/ into your web browser, and you should see the homepage of the docs site! This is a local copy, and you can do whatever to the pages in VScode and it will update every time you save the file.

Submitting back to GitHub

{{0xc000cbbe00 0xc000cbbe00 image-5.png alt text alt text 0xc00075c8a0} 5 false}
Submitting your changes back to GitHub is straightforward. In the “Source Control” panel on the left sde, your should see a list of changes you’ve made. Write a lil message in the changelog and click Commit.

The first time it may get mad at you if you never setup a git username and email. To fix this, in the terminal type: git config --global user.name "Your Username" then: git config --global user.email youremail@example.com

{{0xc000cbbe00 0xc000cbbe00 image-6.png alt text alt text 0xc00075cde0} 6 false}

You’ll need to push your changes after committing. Click the lil up arrow to send everything off to be built!

Occasionally you’ll need to sync up with the server. VSCode more or less automatically warns you about this, and should prompt you in the side panel. Syncing will update your local copy of the site to whatever is current.

Just like editing in GitHub itself, this site automatically deploys - IE any changes you submit trigger a build that will go live usually in around 40 seconds.