From 720209c18542537dc493457b0051e2588420f184 Mon Sep 17 00:00:00 2001 From: Kara Moscoe Date: Wed, 27 Nov 2024 13:46:31 -0800 Subject: [PATCH] additions to style guide --- README.md | 35 ++++++++++++++++------------------- STYLE_GUIDE.md | 15 ++++++++++++++- 2 files changed, 30 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 48f305e6c..a11a223c4 100644 --- a/README.md +++ b/README.md @@ -22,9 +22,11 @@ To see the extent of data we have today, [browse the Knowledge Graph](https://da The Data Commons documentation uses [Kramdown](https://kramdown.gettalong.org/syntax.html) Markdown. -## Navigation +## Navigation and breadcrumbs -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. +The navigation bar and breadcrumbs are generated automatically from the YAML "front matter" at the top of each Markdown file, using the `parent`, `grand_parent` and `great_grand_parent` tags. See [Using YAML front matter](https://docs.github.com/en/contributing/writing-for-github-docs/using-yaml-frontmatter) for details. + +To disable a page from showing up in the navigation, use `exclude_from_nav: true`. ## Build locally @@ -36,7 +38,7 @@ The documentation site is built using Jekyll. To run this locally: You can continue to make local changes and just refresh the browser. You will need to rerun `bundle exec jekyll serve` if you make changes that affect the overall site, such as changes to YAML files, cross-page links, etc. -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. +> **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 @@ -44,22 +46,20 @@ Apache 2.0 ## Contribute changes +Be sure to follow [the style guide](STYLE_GUIDE.md) when making any changes to the content of the docsite repo. + ### One-time setup steps +This is a suggested way to set up your forks and remotes: + 1. In https://github.com/datacommonsorg/docsite, click the **Fork** button to fork the repo. 1. Clone your forked repo to your desktop: - - 
-    git clone https://github.com/USER_NAME/docsite
-
- + 
git clone https://github.com/USER_NAME/docsite
This adds your fork as the remote called `origin`. - 1. Add `datacommonsorg/docsite` repo as a remote: - - 
-    git remote add REMOTE_NAME https://github.com/datacommonsorg/docsite.git
-
+ 
git remote add REMOTE_NAME https://github.com/datacommonsorg/docsite.git
+1. If this is your first time contributing to a Google Open Source project, follow the +steps in [CONTRIBUTING.md](CONTRIBUTING.md) to sign a CLA. ### Create a pull request @@ -79,15 +79,12 @@ git commit -m "COMMIT_MESSAGE" git push -u origin BRANCH_NAME -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. - -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) -when submitting documentation PRs. +Then, in https://github.com, in your forked repo, you can create a pull request. You will need to assign at least one reviewer to approve. Wait for approval of the pull request and merge the change. +> **Tip:** If you are working on multiple PRs/branches at a time, and switching between them, it's desirable to use `git switch --discard-changes` instead of `git checkout`. This prevents changes in the local work tree (committed or not) from automatically bleeding from one branch to another, and keeps the PR diffs clean. + ## Support For general questions or issues, please open an issue on our diff --git a/STYLE_GUIDE.md b/STYLE_GUIDE.md index 7f817e823..befa764e8 100644 --- a/STYLE_GUIDE.md +++ b/STYLE_GUIDE.md @@ -1,3 +1,4 @@ + # Documentation style guide ## General rules @@ -18,8 +19,20 @@ Absolute links are against the repo root and must be specified _with .html exten ``` [Place types](/place_types.html) ``` +## External links + +Any links that go to sites outside of the Docsite should open in a new tab/window. Be sure to use `target="_blank"` in the markup for these links. + +## Redirects + +Whenever you move or delete files, you should be sure to redirect them. For any internal redirects, add `redirect_from` and the old path(s) to the front matter of the new (target) page. +For redirects to an external page, remove the content from the original page, change its layout to `redirect`, and add`redirect_to` tag in the front matter. + +## Tabbed content -IMPORTANT: Section links only work with absolute links. For example, if you have a section in file `api/index.md` defined as `{#authentication}`, any links to it must specify the absolute path, i.e. `/api/index.html#authentication`. +If you'd like to use tabs to allow the user to select the content, use the following: +- For pages that include a single group of tabs, include `assets/js/api-doc-tabs.js` and the styles from `_sass/api_documentation.scss`. +- For pages that have several groups of tabs on the page, include `assets/js/customdc-doc-tabs.js` and the styles from `_sass/custom_dc.scss`. Be sure to include the JS file at the _end_ of the Markdown file so that all groups work correctly. ## TOCs