You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+2Lines changed: 2 additions & 0 deletions
Original file line number
Diff line number
Diff line change
@@ -85,6 +85,8 @@ You can use the GitHub user interface :pencil2: for some small changes, like fix
85
85
## Working in the github/docs repository
86
86
Here's some information that might be helpful while working on a Docs PR:
87
87
88
+
-[Development](/contributing/development.md) - This short guide describes how to get this app running on your local machine.
89
+
88
90
-[Content markup reference](/contributing/content-markup-reference.md) - All of our content is written in GitHub-flavored Markdown, with some additional enhancements.
89
91
90
92
-[Content style guide for GitHub Docs](/contributing/content-style-guide.md) - This guide covers GitHub-specific information about how we style our content and images. It also links to the resources we use for general style guidelines.
Copy file name to clipboardExpand all lines: README.md
+2-60Lines changed: 2 additions & 60 deletions
Original file line number
Diff line number
Diff line change
@@ -7,16 +7,12 @@ GitHub's Docs team works on pre-production content in a private repo that regula
7
7
In this article:
8
8
-[Contributing](#contributing)
9
9
-[READMEs](#readmes)
10
-
-[Developing](#developing)
11
-
-[Site structure](#site-structure)
12
-
-[Error handling](#error-handling)
13
-
-[Search](#search)
14
10
-[License](#license)
15
11
-[Contributors ✨](#contributors-)
16
12
17
13
## Contributing
18
14
19
-
:memo: To find out how you can best contribute to GitHub's product documentation, see [CONTRIBUTING.md](/CONTRIBUTING.md).
15
+
:memo: To find out how you can best contribute to GitHub's product documentation, see the [CONTRIBUTING](/CONTRIBUTING.md) guide.
20
16
21
17
:mega: If you'd like help troubleshooting a PR, have a great new idea, or want to share something amazing you've learned in our docs, join us in [discussions](https://github.com/github/docs/discussions).
22
18
@@ -31,6 +27,7 @@ In this article:
31
27
In addition to the README you're reading right now, this repo includes other READMEs that describe the purpose of each subdirectory in more detail:
@@ -44,61 +41,6 @@ In addition to the README you're reading right now, this repo includes other REA
44
41
-[stylesheets/README.md](stylesheets/README.md)
45
42
-[tests/README.md](tests/README.md)
46
43
47
-
## Developing
48
-
49
-
This site is powered by Node.js! :turtle::rocket:
50
-
51
-
You'll need **Node.js v12** to run the site. If you're using nodenv (you can
52
-
run `nodenv version` to find out which Node.js version you're on), read the
53
-
[nodenv](#nodenv) section for instructions on switching to Node.js 12. If you're
54
-
not using nodenv, the best way to install Node.js is to
55
-
[download the LTS installer from nodejs.org](https://nodejs.org).
56
-
57
-
Once you've installed Node.js, open up Terminal and run the following:
58
-
59
-
```sh
60
-
git clone https://github.com/github/docs-internal
61
-
cd docs-internal
62
-
npm install
63
-
npm start
64
-
```
65
-
66
-
You should now have a running server! Visit [localhost:4000](http://localhost:4000) in your browser. It will automatically restart as you make changes to site content.
67
-
68
-
When you're ready to stop your local server, type <kbd>CTRL</kbd><kbd>c</kbd> in your terminal window.
69
-
70
-
## Site structure
71
-
72
-
This site was originally written in [Jekyll](https://jekyllrb.com/) and later
73
-
[Nanoc](https://nanoc.ws/), both of which are Ruby static site generators.
74
-
This site is now a dynamic Node.js webserver powered by Express, using middleware
75
-
to add support for proper HTTP redirects, language header detection, and dynamic
76
-
content generation to support the various flavors of GitHub's product documenation,
77
-
like dotcom and GitHub Enterprise. For more context on why this change was made,
78
-
see the [new help.github.com](https://github.com/github/product-documentation/tree/master/new-docs-site#static-vs-dynamic)
79
-
proposal doc.
80
-
81
-
The tech powering the site is now different, but many of the tried-and-true
82
-
authoring conventions of the original Jekyll site have been preserved:
83
-
84
-
- Content is written in Markdown files which live in the `content` directory.
85
-
- Content can use the Liquid templating language.
86
-
- Files in the `data` directory are available to templates via the `{% data %}` tag.
87
-
- Markdown files can contain [frontmatter](https://jekyllrb.com/docs/front-matter).
88
-
- The [`redirect_from`](https://github.com/jekyll/jekyll-redirect-from) Jekyll plugin behavior is supported.
89
-
90
-
See the [Content README](content) for more info.
91
-
92
-
## Error handling
93
-
94
-
Errors generated from requests will be sent to Sentry via `middlware/handle-errors.js`, and the `lib/failbot.js` client. This is a lightweight wrapper for sending exceptions to GitHub's Sentry instance.
95
-
96
-
## Search
97
-
98
-
This site's search functionality is powered by [Algolia](https://www.algolia.com), a third-party service.
99
-
100
-
See [search.md](search.md) for details.
101
-
102
44
## License
103
45
104
46
The GitHub product documentation in the assets, content, and data folders are licensed under a [CC-BY license](content/LICENSE).
Copy file name to clipboardExpand all lines: contributing/README.md
+1Lines changed: 1 addition & 0 deletions
Original file line number
Diff line number
Diff line change
@@ -4,6 +4,7 @@ Check out our [contributing.md](../CONTRIBUTING.md) to see all the ways you can
4
4
5
5
Here, you'll find additional information that might be helpful as you work on a pull request in this repo.
6
6
7
+
-[development](./development.md) - steps for getting this app running on your local machine
7
8
-[content markup reference](./content-markup-reference.md) - how to use markup and features specific to the GitHub Docs site
8
9
-[content style guide](./content-style-guide) - style guidance specific to GitHub Docs content and additional resources for writing clear, helpful content
9
10
-[deployments](./deployments.md) - how our staging and production environments work
This document describes the process for running this application on your local computer.
4
+
5
+
## Getting started
6
+
7
+
This site is powered by Node.js! :sparkles::turtle::rocket::sparkles:
8
+
9
+
It runs on macOS, Windows, and Linux environments.
10
+
11
+
You'll need **Node.js v12** to run the site. If you're using [`nodenv`](https://github.com/nodenv/nodenv), read the [`nodenv` docs](#nodenv) below for instructions on switching to Node.js 12. If you're not using `nodenv`, the best way to install Node.js is to [download the LTS installer from nodejs.org](https://nodejs.org).
12
+
13
+
Once you've installed Node.js (which includes the popular `npm` package manager), open Terminal and run the following:
14
+
15
+
```sh
16
+
git clone https://github.com/github/docs
17
+
cd docs
18
+
npm install
19
+
npm start
20
+
```
21
+
22
+
You should now have a running server! Visit [localhost:4000](http://localhost:4000) in your browser. It will automatically restart as you make changes to site content.
23
+
24
+
When you're ready to stop your local server, type <kbd>CTRL</kbd><kbd>c</kbd> in your terminal window.
25
+
26
+
## Site structure
27
+
28
+
This site was originally a Ruby on Rails web application. Some time later it was converted into a static site powered by [Jekyll](https://jekyllrb.com/). A few years after that it was migrated to [Nanoc](https://nanoc.ws/), another Ruby static site generator.
29
+
30
+
Today it's a dynamic Node.js webserver powered by Express, using [middleware](../middleware/README.md) to support proper HTTP redirects, language header detection, and dynamic content generation to support the various flavors of GitHub's product documentation, like GitHub.com and GitHub Enterprise Server.
31
+
32
+
The tooling for this site has changed over the years, but many of the tried-and-true authoring conventions of the original Jekyll site have been preserved:
33
+
34
+
- Content is written in Markdown files, which live in the `content` directory.
35
+
- Content can use the [Liquid templating language](liquid-helpers.md).
36
+
- Files in the `data` directory are available to templates via the `{% data %}` tag.
37
+
- Markdown files can contain [frontmatter](https://jekyllrb.com/docs/front-matter).
38
+
- The [`redirect_from`](https://github.com/jekyll/jekyll-redirect-from) Jekyll plugin behavior is supported.
39
+
40
+
For more info about working with this site, check out these READMEs:
[nodenv](https://github.com/nodenv/nodenv) is a tool for managing multiple Node.js versions on your local machine. It is **not required** to run this app, but you may already have it installed if you've worked on other projects that use Node.js.
60
+
61
+
To install Node.js 12 and make it your default version, run this command:
62
+
63
+
```sh
64
+
nodenv install 12.8.0 && nodenv global 12.8.0
65
+
```
66
+
67
+
You may sometimes see a warning when running npm scripts with nodenv:
68
+
69
+
```sh
70
+
npm WARN lifecycle The node binary used for scripts is [...] but npm is using [...]
71
+
```
72
+
73
+
This is due to nodenv's overriding behavior. To silence this harmless warning, the [nodenv docs](https://github.com/nodenv/nodenv/wiki/FAQ#npm-warning-about-mismatched-binaries) recommend running the following command from any directory:
0 commit comments