first commit

CONTRIBUTING.md

@@ -0,0 +1,154 @@
+# GitHub Handbook Content
+
+The GitHub Handbook website is a [Jekyll static site](https://jekyllrb.com/).
+
+Most of the content is editable as regular Markdown in files inside the ```_pages``` folder.
+
+If you want to modify HTML (e.g., create new pages that show in a sidebar), and you're not familiar with Jekyll, you'll want to ask a developer to help you.
+
+<details>
+<summary>Configuration Variables</summary>
+<br>
+
+Update the following variables to customize this site to your organization:
+
+<details>
+<summary><code>_config.yml</code></summary>
+<br>
+
+Update the values for the following variable groups:
+
+- <code>contact-handbook</code>
+- <code>org</code>
+- <code>support</code>
+- <code>slack</code>
+- <code>conical_domain</code>
+- <code>url</code>
+- <code>baseurl</code>
+- <code>custom</code>
+
+</details>
+</br>
+
+<details>
+<summary><code>_main.scss</code></summary>
+<br>
+
+Update the following to change the logo image:
+
+<code>.usa-hero {  
+    background-image:</code>
+
+Image file is saved here:
+
+<code>/docs/assets/img/logo/github-handbook.png</code>
+
+</details>
+</br>
+
+</details>
+</br>
+
+<details>
+<summary>Where Things Live</summary>
+<br>
+
+* ```_data``` - simple .yml files containing data that is read into other pages
+
+* ```_includes``` - small pieces of HTML that are included into other pages, e.g., the header, the footer, etc.
+
+* ```_layouts``` - HTML structures for each page type:
+  * ```base``` - the basic HTML structure for all pages
+  * ```home``` - the HTML structure for the Home page
+  * ```jump-menu``` - the HTML structure for pages with a right side jump-down menu
+  * ```no-sidebar``` - the HTML structure for pages that do not have a sidebar, e.g., the contact page
+  * ```page``` - the HTML structure for pages with a sidebar  
+
+* ```_posts``` - announcements that appear on the site
+
+* ```_sass``` - the uncompiled/editable CSS files
+
+* ```assets``` - the public assets folder for images, CSS, JS, etc
+
+* ```Gemfile``` and ```Gemfile.lock``` - no need to update unless you add new Gems
+
+* ```_config.yml``` - the file containing configuration information for Jekyll
+
+* ```manifest.json``` - the manifest file for mobile icons
+
+</details>
+</br>
+
+<!-- markdownlint-disable -->
+<details>
+<summary>Page Structure</summary>
+<br>
+
+### General
+
+All editable site pages live in the ```_pages``` folder.
+
+### Home page
+
+* The Home page is a custom page with its own layout -- ```_layouts/home.html```.
+
+* Most of the content is editable as [Jekyll front matter](https://jekyllrb.com/docs/front-matter/) in the ```_pages/index.md``` file.
+
+* Other editable content is noted in the Jekyll front matter in the same file.
+
+### Pages with Sidebars
+
+* Pages in the Delivery Guide and Resources section contain a sidebar and use the ```_layouts/page.html``` layout.
+
+* These pages are more complex, for example, they may use an include for secondary navigation or to include small bits of HTML.
+  * You can see where these pieces are included in the page file. For example, in the ```_pages/delivery/build-and-test-1.md``` file, you'll see ```{% include phase-planning.html phase="Build and Test" %}```. This says "include the ```_includes/phase-resources.html``` HTML and note the phase as *build and test*."
+    * Inside the ```_includes/phase-resources.html``` file, you'll see ```{{ site.data.phase-resources.guides | markdownify }}```. This says "include the content in the *guides* section of the ```_data/phase-resources``` file.
+
+* Most of the content is editable as Markdown below the three dashes (```---```) in the relevant ```_pages``` files, e.g., the ```_pages/delivery/build-and-test-1.md``` file.
+
+### Miscellaneous Pages
+
+> Contact and 404
+
+* These pages use the ```_layouts/no-sidebar.html``` layout.
+
+* Most of the content is editable as Markdown below the three dashes (```---```) in the relevant ```_pages``` files, e.g., the ```_pages/contact.md``` file.
+
+* Other editable content is noted in the Jekyll front matter in the same file.
+
+</details>
+</br>
+
+<details>
+<summary>Using Markdown in Content</summary>
+<br>
+
+### General
+
+You can use Markdown as normal in ```_pages``` files below the three dashes (```---```). E.g., paragraphs, bullet points, etc.
+
+The ```_sass/main.scss``` file styles all the Markdown.
+
+There is a special CSS style for a blockquote, which you can use by typing ```> content goes here``` in your Markdown. For example,
+> This is not a fancy blockquote.
+
+Markdown is not allowed in Jekyll front matter (the content between the three dashes (```---```).
+
+* If you need to style something in front matter, you'll need to use regular HTML tags.
+
+### Links
+
+To create links to pages inside the Handbook, use this format:
+
+* ```[User research guide]({{site.baseurl}}/resources/user-research)```
+  * The ```{{site.baseurl}}``` portion helps Jekyll create the proper link.
+
+To create links to pages outside the Handbook, use offsite links in this format:
+
+* ```<a target="_blank" href="{{ site.baseurl }}/resources/more/checkpoint">```
+  * This opens the link in a new tab/page.
+
+</details>
+</br>
+
+<!-- markdownlint-restore -->

README.md

@@ -0,0 +1,33 @@
+# GitHub Handbook
+
+## Information
+
+The `pages` site is driven by [Jekyll static site](https://jekyllrb.com/).
+
+GitHub `pages` sites can be `private` or `public` in github.com. However, the repository behind those pages sites can be `private` or `internal` (if hosted in an organization) which restricts the users that have `write-access` to those that have explicit permission.
+
+## Contributing as a member of the repository
+
+* See [CONTRIBUTING.md](/CONTRIBUTING.md) for
+  * How this Jekyll site is organized
+  * How to use Markdown for writing/editing content
+  * How to update the ```modified-date``` that displays on site pages.
+
+## Development
+
+This is a [Jekyll static site](https://jekyllrb.com/).
+
+### Setting up your local dev environment
+
+1. Clone/fork this repo.
+2. For best results (urls work correctly), run locally at 127.0.0.1:4000/
+
+    ```shell
+    bundle exec jekyll serve --incremental
+    ```
+
+3. Whenever you make a change to content, also change the ```modified-date``` in the yml at the top of the relevant ```.md``` file. See `Updating Page Dates` section on the [CONTRIBUTING.md](/CONTRIBUTE.md) page for more info.
+
+## Colophon
+
+* Jekyll front-end code inspired by [login.gov](https://www.login.gov)

docs/Gemfile

@@ -0,0 +1,21 @@
+source "https://rubygems.org"
+
+# Hello! This is where you manage which Jekyll version is used to run.
+# When you want to use a different version, change it below, save the
+# file and run `bundle install`. Run Jekyll with `bundle exec`, like so:
+#
+#     bundle exec jekyll serve
+#
+# This will help ensure the proper Jekyll version is running.
+# Happy Jekylling!
+# gem "jekyll", "~> 3.8.3"
+
+# If you want to use GitHub Pages, remove the "gem "jekyll"" above and
+# uncomment the line below. To upgrade, run `bundle update github-pages`.
+gem "github-pages", group: :jekyll_plugins
+
+# Windows does not include zoneinfo files, so bundle the tzinfo-data gem
+gem "tzinfo-data", platforms: [:mingw, :mswin, :x64_mingw, :jruby]
+
+# Performance-booster for watching directories on Windows
+gem "wdm", "~> 0.1.0" if Gem.win_platform?