added plugin support for relative links and make fixes/updates to other .md files

CONTRIBUTING.md

@@ -1,9 +1,9 @@
-# How to Contribute
+# How to contribute
 
 We'd love to accept your patches and contributions to this project. There are
 just a few small guidelines you need to follow.
 
-## Contributor License Agreement
+## Contributor license agreement
 
 Contributions to this project must be accompanied by a Contributor License
 Agreement. You (or your employer) retain the copyright to your contribution;
@@ -22,7 +22,7 @@ use GitHub pull requests for this purpose. Consult
 [GitHub Help](https://help.github.com/articles/about-pull-requests/) for more
 information on using pull requests.
 
-## Community Guidelines
+## Community guidelines
 
 This project follows [Google's Open Source Community
 Guidelines](https://opensource.google/conduct/).

Gemfile

@@ -16,6 +16,7 @@ end
 
 group :jekyll_plugins do  
   gem "jekyll-tabs"
+  gem "jekyll-relative-links"
 end
 
 gem "webrick", "~> 1.8"

Gemfile.lock

@@ -277,8 +277,9 @@ DEPENDENCIES
   github-pages
   jekyll-feed (~> 0.6)
   jekyll-redirect-from
+  jekyll-relative-links
   jekyll-tabs
   webrick (~> 1.8)
 
 BUNDLED WITH
-   2.4.21
+   2.4.21

README.md

@@ -1,9 +1,9 @@
 [![Build and deploy to GitHub Pages](https://github.com/datacommonsorg/docsite/actions/workflows/github-pages.yml/badge.svg)](https://github.com/datacommonsorg/docsite/actions/workflows/github-pages.yml)
 
-# Data Commons Documentation Site
+# Data Commons documentation site
 
 This repo hosts Data Commons API documentation
-available at https://docs.datacommons.org/.
+available at https://docs.datacommons.org/. The site is hosted in [Github Pages](https://pages.github.com/), and generated by [Jekyll](https://jekyllrb.com/).
 
 ## About Data Commons
 
@@ -18,50 +18,75 @@ to make public data accessible to everyone.
 
 To see the extent of data we have today, [browse the Knowledge Graph](https://datacommons.org/browser).
 
-## Developing locally
+## Markdown
+
+The Data Commons documentation uses [Kramdown](https://kramdown.gettalong.org/syntax.html) Markdown.
+
+## Navigation
+
+The navigation bar is generated automatically from the YAML "front matter" at the top of each Markdown file. See [Using YAML front matter](https://docs.github.com/en/contributing/writing-for-github-docs/using-yaml-frontmatter) for details.
+
+## Build locally
 
 The documentation site is built using Jekyll. To run this locally:
 
 1. Install [Ruby](https://jekyllrb.com/docs/installation/)
 1. Run `bundle update`
 1. Run `bundle exec jekyll serve --incremental`
 
-If you make changes to yml files, re-run `bundle exec jekyll serve`
+You can continue to make local changes and just refresh the browser. If you make changes to YAML files, re-run `bundle exec jekyll serve`
+
+Tip: If you want to make the staged site accessible to others (and not just on the loopback), add `--host 0.0.0.0` to the command. Then, users can access the site using the hostname of the machine where the site is running.
 
 ## License
 
 Apache 2.0
 
-## Contributing
+## Contribute changes
+
+### One-time setup steps
 
-In https://github.com/datacommonsorg/docsite, click on "Fork" button to fork the repo.
+1. In https://github.com/datacommonsorg/docsite, click the **Fork** button to fork the repo.
+1. Clone your forked repo to your desktop:
 
-Clone your forked repo to your desktop.
+    <pre>
+    git clone https://github.com/<var>USER_NAME</var>/docsite
+    </pre>
 
-Add datacommonsorg/docsite repo as a remote:
+    This adds your fork as the remote called `origin`.
 
-```shell
-git remote add dc https://github.com/datacommonsorg/docsite.git
-```
+1. Add `datacommonsorg/docsite` repo as a remote:
 
-Every time when you want to send a Pull Request, do the following steps:
+    <pre>
+    git remote add <var>REMOTE_NAME</var> https://github.com/datacommonsorg/docsite.git
+    </pre>
 
-```shell
+### Create a pull request
+
+Every time you want to create a pull request, create a new branch and sync to the master branch:
+
+<pre>
 git checkout master
-git pull dc master
-git checkout -b new_branch_name
-# Make some code change
+git pull master
+git checkout -b <var>BRANCH_NAME</var>
+</pre>
+
+Make your changes, and then create the PR as follows:
+
+<pre>
 git add .
-git commit -m "commit message"
-git push -u origin new_branch_name
-```
+git commit -m "<var>COMMIT_MESSAGE<var>"
+git push -u origin <var>BRANCH_NAME</var>
+</pre>
+
+Then, in github.com, in your forked repo, you can send a pull request. You will need to assign at least one reviewer to approve.
 
-Then in your forked repo, you can send a Pull Request. If this is your first
+If this is your first
 time contributing to a Google Open Source project, you may need to follow the
-steps in [contributing.md](contributing.md). Be sure to follow [the style guide](STYLE_GUIDE.md)
+steps in [CONTRIBUTING.md](CONTRIBUTING.md). Be sure to follow [the style guide](STYLE_GUIDE.md)
 when submitting documentation PRs.
 
-Wait for approval of the Pull Request and merge the change.
+Wait for approval of the pull request and merge the change.
 
 ## Support
 

STYLE_GUIDE.md

@@ -1,10 +1,55 @@
-# Decision documentation
+# Documentation style guide
 
-## Style guide
+## General rules
 
-We use the [Google style guide](https://developers.google.com/style/code-in-text) as our writing standard.
+We use the Google [Developer Documentation Style Guide](https://developers.google.com/style/) as our writing standard. Please follow the guidelines in that guide when making documentation changes.
 
-## Pluralizing nodes in Data Commons
+## Links
+
+The site supports both absolute and [relative links](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#relative-links); you can use either. Relative links work as in standard Github Markdown, using `.md` extensions. For example, for a
+target page at a higher level of the tree than a source page, you can use this:
+
+```
+[Place types](../place_types.md)
+```
+
+Absolute links are against the repo root and must be specified _with .html extensions_. For example:
+
+```
+[Place types](/place_types.html)
+```
+
+## TOCs
+
+To add a TOC to a page, use the following Markdown:
+
+```
+* TOC
+{:toc}
+```
+
+## Page titles
+
+Add an H1 heading at the start of a page to get a page title. Be sure to exclude it from showing up in a TOC. For example:
+
+```
+{:.no_toc}
+# Here is a page title
+```
+## Multiline commands
+
+When you provide multiline commands, separated by the `\` character, be sure to omit any extra spaces after the backslash, or it will cause failures when users try to copy and paste. For example, if you have a command like this:
+
+```
+docker run -it \  
+-p 8080:8080 \  
+-e DEBUG=true \  
+--env-file $PWD/custom_dc/sqlite_env.list \  
+gcr.io/datcom-ci/datacommons-website-compose:stable  
+```
+Make sure there are no trailing spaces after the backslashes on each line.
+
+## Plurals
 
 When describing a place or `Place`, be careful to distinguish between Data Commons `Place` objects and places that one might visit, and use the appropriate styling for each. Here are two sample sentences that illustrate the distinction:
 

_config.yml

@@ -25,6 +25,7 @@ plugins:
   - jekyll-feed
   - jekyll-redirect-from
   - jekyll-tabs
+  - jekyll-relative-links
 
 sass:
   style: compressed