Intro to VS Code - roman-gardens/gre GitHub Wiki

GRE recommends the use of VS Code (Microsoft's Visual Studio Code) for working with the GRE source files.

First, make sure you have completed the steps in Setting up your own copy of GRE.

Once you have done that, whenever you open VS Code, it should remember where you left off, with all the files you had open in your last session. If you do not see them, try clicking the "Explorer" icon (top icon on the left):

You can also restore a previous session by going to the "File" menu and clicking "Open Recent".

Previewing a garden with Hugo

The garden articles can be found in the Explorer panel on the left, under "content" > "place", where they are organized by province and location. When viewing the source code for a garden, there are two main ways of previewing what the article may look like. One option is to use the internal Markdown Preview feature of VS Code:

  • In VS Code, press CTRL-SHIFT-P and then type to find "Markdown: Open Preview to the Side"

This opens a sub-window to the right, showing the Markdown code partially converted into headings, bulleted lists, links etc. However it does not do anything to transform shortcodes for images, keywords, or ids, and does not show page metadata from the front matter.

The second option is to use Hugo to generate a local copy of the website, and view the page in your web browser:

  • In VS Code, open the terminal ("View" menu > "Terminal")
  • Type the command hugo server -D and press ENTER (the -D tells hugo to include drafts)
  • It may take several seconds for Hugo to build the site and start the server. When it is ready, you should see the message: 
    Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop
  • Control-click the http://localhost:1313 URL in the terminal to open the link in your web browser
  • You should see the page as it would appear on the real website -- except it is just running on your local computer.

Making edits

When you make edits in VS Code, you will see a white circle on the tab at the top, to the right of the filename:

This white circle indicates that there are unsaved edits to the page.

  • Press CTRL-S to save your changes to the file

The white circle should disappear, but now you should see a blue circle with a number on the "Source Control" icon on the left:

The number indicates how many files have been updated. To review your changes:

  • Click the "Source Control" icon
  • You should see a list of files under the heading "Changes"
  • Click the filename to see a "diff", showing the file before and after.

Red highlighting shows lines that have been deleted. Green highlighting shows lines that have been added. If you changed some of the text on a line, it may be represented as a deletion and an addition.

The "diff" may be viewed inline, or as separate before/after views. To toggle between these options, click the "..." icon at the top right and toggle the "inline view" on or off, depending on your preference.

If the changes look good, you can follow these steps to move the updates up to your copy of GRE on GitHub:

  • In the "Source Control" panel on the left, click the + to the right of the filename to "stage" the change
  • (Repeat as needed for other files, or click the + to the right of the "Changes" header to stage them all at once)
  • Type a short message that broadly describes your changes. There is no need to go into detail, because every line change is tracked. A good commit message might be something like one of the following:
    • "Reviewed gardens in Achaea"
    • "Added keywords in Nemausus"
    • "Fixed typos"
  • Click the "Commit" button
  • Click the "Sync Changes" button -- this will push your changes up to the GRE repo in your GitHub account.