Github Book

You can create your own website that looks like a ‘book’ by copying an existing template in Github and editing it in RStudio.

Prepare to do Great Things! Make sure you have gone through all the steps in the ‘Getting Started’ section of the Open Sciences chapter of this manual.
Copy a template of Great Things!

Copy an existing template to your own Github account. Go to NOAA Quarto Template and copy template to your Github Repository following the directions on the README.md. Give it an appropriate name and make sure it is PUBLIC.
Copy to your desktop to make it a Greater Thing!

Using Github Desktop, Clone repository using URL (File-> Clone Repository). Copy the URL of your repository site (the URL of your copy of the Great Things Repository on your github account), and save project to your Documents-> Github folder (use defaults). See this Introduction to Git/Github tutorial for more help.
Use RStudio to Modify Great Thing to make it Greater!

In RStudio, in the top right corner, select the project dropdown to Add New R Project from an Existing Project– and browse to select the appropriate folder in Documents-> Github. Examine the documents:
1. README.md
  
  This is the README file that will appear on your repository page.
2. index.qmd
  
  This will serve as your ‘home’ page for the web-book that is created
3. contents folder
  
  This folder will contain the ‘pages’ (chapters) for your web-book
4. _quarto.yml
  
  This will define the layout of your web-book
  
  (Insert picture of Layout)
Modify README.md

If you are using the latest version of RStudio (with quarto), you can modify your file using the Source Code or the Visual Editor. This is an RMarkdown file, so you can use R markdown language, or, if you prefer, you can use the visual editor which is more user-friendly. If you copy/paste an existing document into the visual editor, much of the existing formatting will be retained.
Modify and Rename files in Contents Folder

Each of the existing qmd (Quarto) files in the contents folder have additional instructions to help you format your ‘book’ in Quarto. You may want to keep them, or you can always review the original template web-page for this information. Read the ‘Add Content’ page here to understand the minimal information you need for each of these pages in your contents folder.

For each page in your website (or chapter in your book), you will want to have a qmd file in this folder. You can open one of the existing qmd files and File-> Save As and save it as another name. Retain the minimal information needed for your page (see the Add Contents page), and then add your content using either the source code or visual editor. Make sure you SAVE each file when you are finished!
Modify _quarto.yml file

The _quarto.yml file identifies the structure of the web-book. Make changes to the website (Title, site & repo URL), the Sidebar (link to your preferred logo, link the globe icon to your website and link the github icon to your github URL and rename both of these). Finally– you will want to identify the contents.

The contents are each of your chapters (or web- pages). Each chapter has two lines of information:
1. href: refers to the name of the relevant qmd file (located in the contents folder).
2. text: this is the text you will see on the sidebar of the web-book.
  
  The first contents page (home page) will link to the index.qmd file (in the main folder). The others will be in the contents folder, and therefore their name should be ‘contents/filename.qmd’ (where filename is the name of that qmd file).
Render & View the Web-book

You may want to render and view the web-book locally to be sure it is great.

To Render the document, open the index.qmd file (in the main folder) and click on the ‘Render’ icon near the top (to the right of the save button). Look in the Terminal (lower left section of RStudio) for any errors. Most errors may be due to typos or unsaved modifications. If you still have errors, save everything & reopen RStudio & run again. If you still have errors, go through file by file!

To view the rendered document, open the _site folder, click on the index.html and select ‘View in Web Browser’. Ensure that everything looks as you would expect. You may need to modify, render, view, repeat until it is good. Be sure your project is saved.
Commit & Push to Github

Open Github Desktop and open your project (if it is not already opened). Github desktop will identify the changes you made. At the bottom left, describe the modifications you made to the document, and then select ‘commit’. Once the commit goes through– select ‘Push to Origin’ at the top. This will push changes to your Github repository.
Open your Github repository and check out your Great Things!