Add real content into an Index file May 16 2022

README.md

@@ -1,12 +1,48 @@
-# Write the Docs SF workshop
+# Tutorial: Learn GitHub by building a website
 
-Files for the GitHub for Documentation workshop for Write the Docs - San Francisco. 
+This tutorial was originally presented at the GitHub for Documentation workshop from [Write the Docs - San Francisco](https://www.meetup.com/Write-the-Docs-SF/events/234679051/) on October 27, 2016.
 
-https://www.meetup.com/Write-the-Docs-SF/events/234679051/
+### Original workshop information
 
-To work through the tutorial, start with tutorial-learn-github-pages.md.
+Presenter: Rhonda Glennon, [@rmglennon](https://github.com/rmglennon)
 
-Presented on October 27, 2016
+GitHub enables people to collaborate on projects, and many organizations use it for managing both software code and documentation. At this Write the Docs, you will get started with GitHub by applying its tools to building a documentation website.
 
-Rhonda Glennon
-@rmglennon
+In this hands-on workshop, you will:
+
+- Get an introduction to the Git version control system, terminology, and the GitHub workflow. 
+- Create a simple website with GitHub Pages and use GitHub for documentation. 
+- Learn how you can support open-source projects by contributing documentation.
+
+The session is designed for beginners to GitHub, but all levels are invited.
+
+Bring your laptop so you can follow along with the presentation. Any operating system will work, and you need only a browser. If you are new to GitHub, create a free, personal account at https://github.com/join before arriving to save time.
+
+## Resources from the presentation
+
+Examples of github.io websites
+
+- https://square.github.io/
+- https://microsoft.github.io/
+- https://disney.github.io/
+
+Markdown syntax reference
+
+- https://daringfireball.net/projects/markdown/
+
+Training classes from GitHub
+
+- https://services.github.com/training/
+- Includes free self-paced classes and webinars
+
+GitHub branching and flow diagrams
+- Octopus Git branch: http://imgur.com/gallery/YG8In8X/new
+- GitHub Flow: https://guides.github.com/introduction/flow/
+
+Examples of documentation repositories
+
+- CircleCI has a repository with only documentation-related files: https://github.com/circleci/circleci-docs
+- Kubernetes repository contains both code and documentation files: https://github.com/kubernetes/kubernetes
+- Example pull request about documentation with team discussion: https://github.com/pelias/pelias-doc/pull/163
+
+Make four pull requests by October 31, 2016 and get a free Hacktoberfest t-shirt: https://hacktoberfest.digitalocean.com/

docs/_config.yml

@@ -1,10 +1,10 @@
+# Metadata for the site header and footer
 title: My website
-description: A website showing GitHub Pages
+description: A website made with GitHub Pages
+
+# Set the production website URL when previewing
 baseurl: "/write-the-docs"
 
-# Build settings
+# Markdown parser and theme settings
 markdown: kramdown
 theme: minima
-
-exclude:
-- README.md

tutorial-learn-github-pages.md

@@ -28,15 +28,15 @@ You can review the [GitHub Glossary](https://help.github.com/articles/github-glo
 
 ## Copy the files to your account
 
-To get started, you need to make a copy of the repository containing the tutorial data files. You do not have write permissions the source version, but making a copy into your own GitHub account allows you to edit them. This is known as creating a _fork_, or _forking a repository_.
+To get started, you need to make a copy of the repository containing the tutorial data files. You do not have write permissions for the source version, but making a copy into your own GitHub account allows you to edit them. This is known as creating a _fork_, or _forking a repository_.
 
 1. Open a browser to https://github.com and sign in with your account.
-2. Navigate to https://github.com/mapzen/write-the-docs, which contains some files to get you started.
-4. Click the `Fork` button in the top right corner of the page.
+2. Navigate to https://github.com/rmglennon/write-the-docs, which contains some files to get you started.
+3. Click the `Fork` button in the top right corner of the page.
 
-  ![Fork a repository button](images/fork-repo-button.png)
+    ![Fork a repository button](images/fork-repo-button.png)
 
-5. You may be prompted where to place the forked repository. Choose the option that will put the copy into your personal account, rather than forking it into any _organization_ to which you belong. An organization is a group of users on GitHub.
+4. You may be prompted where to place the forked repository. Choose the option that will put the copy into your personal account, rather than forking it into any _organization_ to which you belong. An organization is a group of users on GitHub.
 
 You now have a copy of the repository that you can edit. If you look at the repository name, it shows the name of the source repository from which it was forked.
 
@@ -47,9 +47,7 @@ _Tip: You can download a copy of a repository to your local machine. Doing this
 The files provided for the tutorial include information about the repository's license, some markdown documents, and a `docs` folder. You are going to create a web page from the contents of the `docs` folder.
 
 1. Look at the files in your forked repository.
-2. Click the `docs` folder to display its contents. It contains a `css` folder, which imports a visual theme for the website you will create, and `_config.yml` to set up the website.
-
-  ![Files in the repository](images/repo-files-css-config.png)
+2. Click the `docs` folder to display its contents. It contains `_config.yml` with configuration information to set up the website.
 
 These files are used with [Jekyll](https://jekyllrb.com/), a software library written in Ruby that converts text files, such as the markdown files you see here, into a static website or blog. Jekyll is very flexible, and you can [review the documentation](https://jekyllrb.com/docs/home/) to learn more about how to customize it for your site. [GitHub Pages](https://pages.github.com/), which the free website hosting service you are using in this tutorial, is powered by Jekyll.
 
@@ -63,7 +61,7 @@ Markdown is a lightweight markup language that uses plain text with symbols, lik
 
 1. Be sure you are in the `docs` folder (the path should be `write-the-docs/docs`) and click `Create new file`.
 
-  ![Create new file button](images/create-new-file-button.png)
+    ![Create new file button](images/create-new-file-button.png)
 
 2. In the `Name your file` box, type `index.md`. It is very important that you include the `.md` file extension in the name; otherwise, your website will not be generated.
 3. On the `Edit new file` tab, add all the following text.
@@ -76,7 +74,7 @@ Markdown is a lightweight markup language that uses plain text with symbols, lik
   Hello, world!
   ```
 
-The text between the two lines of hyphens (`---`) is metadata, known as front matter, that Jekyll processes to display the page. You can use variables and other options in the front matter to customize your site.
+The text between the two lines of hyphens (`---`) is metadata, known as front matter, that Jekyll processes to display the page. You can use variables and other options in the front matter to customize your site. GitHub Pages can make any markdown file into a website, so tries to assign the page metadata automatically if it is not present.
 
 You are setting the page layout and giving the page a title. The content that comes after this is what is displayed on your page (Hello, world!).
 
@@ -96,18 +94,26 @@ _Tip: You can click Graphs > Network or the number next to the Fork button, to v
 
 1. Scroll to the `Commit new file` section of the page.
 2. In the first box, type `Create website index file`.
-  This is a commit message, where you can explain your work. Providing a descriptive and meaningful message is important so you and others are able to know what is happening in this group of edits and be able to refer back to them in the future. If you do not add any text, GitHub includes a default message.
-3. Click `Create a new branch for this commit and start a pull request.` On this page, GitHub is combining three actions into one: creating a branch for your changes, committing your them to the branch, and starting a pull request.
-  _Tip: When you are making more complex edits, you may want to create a branch from the Branch menu and reuse the branch for multiple commits._
+
+    This is a commit message, where you can explain your work. Providing a descriptive and meaningful message is important so you and others are able to know what is happening in this group of edits and be able to refer back to them in the future. If you do not add any text, GitHub includes a default message.
+
+3. Click `Create a new branch for this commit and start a pull request.`
+
+    On this page, GitHub is combining three actions into one: creating a branch for your changes, committing your them to the branch, and starting a pull request.
+
+    _Tip: When you are making more complex edits, you may want to create a branch from the Branch menu and reuse the branch for multiple commits._
+
 4. GitHub automatically suggests a branch name based on your username. You can use it or type your own, such as `new-index-file`. The branch name should be descriptive, and some organizations may have naming standards.
 
-  ![Commit new file](images/index-file-commit-small.png)
+    ![Commit new file](images/index-file-commit-small.png)
 
 5. Click `Propose new file`.
-  The page refreshes and you are on a page where you can open a pull request to propose your changes be merged into the master branch. The subject of the pull request is the commit message you typed before.
+
+    The page refreshes and you are on a page where you can open a pull request to propose your changes be merged into the master branch. The subject of the pull request is the commit message you typed before.
+
 6. Add some additional information about your the changes you are proposing in the comment box, such as `This adds an index file to create the homepage for the website.`
 
-  ![Open a pull request page](images/open-pull-request-small.png)
+    ![Open a pull request page](images/open-pull-request-small.png)
 
 7. Scroll the page and review the other information displayed on the pull request. For example, you can see the list of commits (there is only one) and the changes you made.
 8. Click `Create pull request`.
@@ -124,18 +130,20 @@ In this case, you are the only contributor to this repository and need to review
 
 1. Review the information on the pull request page.
 
-  ![Pull request page](images/pull-request-page-small.png)
+    ![Pull request page](images/pull-request-page-small.png)
 
 2. Below the merge section, type a comment and click `Comment`. Comments are used to discuss the changes. You can use emoji and markdown in your comments.
 
-  ![Add a comment to a pull request](images/pull-request-add-comment-small.png)
+    ![Add a comment to a pull request](images/pull-request-add-comment-small.png)
 
 3. Click `Merge pull request`.
-  Your changes are compatible and do not conflict with the master branch, so can be merged automatically. However, sometimes, when multiple people are editing the same part of a file, GitHub cannot determine which change is correct. If this happens, you may need to use [command-line options](https://help.github.com/articles/resolving-a-merge-conflict-from-the-command-line/) to review and reconcile merge conflicts.
+
+    Your changes are compatible and do not conflict with the master branch, so can be merged automatically. However, sometimes, when multiple people are editing the same part of a file, GitHub cannot determine which change is correct. If this happens, you may need to use [command-line options](https://help.github.com/articles/resolving-a-merge-conflict-from-the-command-line/) to review and reconcile merge conflicts.
+
 4. Click `Confirm merge`.
 5. Click `Delete branch` to remove the temporary branch.
 
-  ![Delete the old branch](images/pull-request-delete-branch.png)
+    ![Delete the old branch](images/pull-request-delete-branch.png)
 
 You have now merged your changes into the master branch, and the pull request status shows as `Merged`. Congratulations if this is your first pull request!
 
@@ -148,16 +156,16 @@ To use GitHub Pages, you need to specify the source of the files used to build t
 - the entire master branch, which is useful if the repository only contains files used for the website
 - the contents of a folder named `docs` in the master branch
 
-The option to use the `docs` folder, which is what you will be doing, allows you to store documentation in the same repository alongside the code it describes. The repository you forked contains all the stylesheets needed to build a website, but GitHub Pages has other options for building your own themes or custom sites.
+The option to use the `docs` folder, which is what you will be doing, allows you to store documentation in the same repository alongside the code it describes. You are using the default visual style, but GitHub Pages has other options for building your own themes or custom sites.
 
 1. Click `Settings` near the top of the page.
 
-  ![Repository settings button](images/repository-settings-button.png)
+    ![Repository settings button](images/repository-settings-button.png)
 
 2. On the main `Options` tab, scroll to the `GitHub Pages` section.
 3. Under `Source`, click `master branch /docs folder`.
 
-  ![GitHub Pages source using the /docs folder](images/github-pages-source.png)
+    ![GitHub Pages source using the /docs folder](images/github-pages-source.png)
 
 4. Click `Save`.
 5. After the page refreshes, scroll back to the `GitHub Pages` section, if necessary, and notice that there is a banner indicating your site is ready to be published.
@@ -176,15 +184,15 @@ You next can replace the "Hello, world!" text with real content. You can copy te
 2. In the root level of the repository, find and open the file named `sample-text-for-website.md`.
 3. Click the `Raw` button to view the plain text, including the markdown formatting.
 
-  ![View the raw file content](images/raw-button.png)
+    ![View the raw file content](images/raw-button.png)
 
 4. Select all the text and copy it.
 5. Navigate to the `index.md` file in the `docs` folder.
 6. Click `Edit this file`.
 
-  ![Start editing the file](images/edit-this-text-button.png)
+    ![Start editing the file](images/edit-this-text-button.png)
 
-7. Delete the "Hello, world!" text, making sure to leave in place the front matter section above it.
+7. Delete the "Hello, world!" text, making sure to leave in place the front matter section above it. (If you do accidentally delete it, GitHub Pages tries to assign the page metadata automatically.)
 8. Paste the text you copied after the second `---` line.
 9. Following the same workflow you did before, commit your changes into a new branch and start a pull request.
 10. Open the pull request, merge your changes into the master branch, and delete the temporary branch.
@@ -201,11 +209,14 @@ Your basic website is complete.
 On your own, here are some of the tasks you can do to continue enhancing your site.
 
 1. Add more pages to your website.
-  - Files you add in the `docs` folder will be at a URL that matches the file name. For example, `about.md` will display at `/about`.
-  - Add a blog to your site by creating a `_posts` folder in the `docs` folder. By default, files should be named `YYYY-MM-DD-my-new-post.md`, where YYYY-MM-DD is the year, month, and day it is posted and the file name. This shows up on your site at a URL similar to `YYYY/MM/DD/my-new-post`.
+
+    - Files you add in the `docs` folder will be at a URL that matches the file name. For example, `about.md` will display at `/about`.
+    - Add a blog to your site by creating a `_posts` folder in the `docs` folder. By default, files should be named `YYYY-MM-DD-my-new-post.md`, where YYYY-MM-DD is the year, month, and day it is posted and the file name. This shows up on your site at a URL similar to `YYYY/MM/DD/my-new-post`.
+
 2. Customize the site configuration in `_config.yml`.
 3. Experiment with other themes, including the automatic site generation tools under the repository settings.
 4. Make a local copy of the repository and learn how to use the command-line interface to modify the files.
+5. Improve the original repository by [making a pull request](https://help.github.com/articles/creating-a-pull-request-from-a-fork/) from enhancements in your fork.
 
 _Tip: If you want to remove your GitHub Pages site or delete the repository, open the repository settings._
 
@@ -217,4 +228,4 @@ Documentation can be an easy way to get started contributing to a project. For e
 
 If you find a bug or have suggestions for a project but are unable or do not want to fix them yourself, report an _issue_ in the repository to notify the contributors. You can also use the issues list to find known problems that you may be able to assist with, which are sometimes tagged with `help wanted`.
 
-GitHub repositories often contain [guidelines for contributing](https://help.github.com/articles/setting-guidelines-for-repository-contributors/) to the project, including how to format your pull request and the code of conduct. Be sure to review and follow these instructions to help maintain a positive open-source community.
+GitHub repositories often contain [guidelines for contributing](https://help.github.com/articles/setting-guidelines-for-repository-contributors/) to the project, including how to format your pull request and the code of conduct. Be sure to review and follow these instructions to help maintain a positive open-source communit