Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

repo sync #115

Merged
merged 1 commit into from
Oct 6, 2020
Merged

repo sync #115

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
128 changes: 36 additions & 92 deletions content/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,12 @@

The `/content` directory is where all the site's (English) Markdown content lives!

See the [markup reference guide](contribution/content-markup-reference.md) for more information about supported Markdown features.
See the [markup reference guide](contributing/content-markup-reference.md) for more information about supported Markdown features.

See the repository's top-level [README](../README.md) for general information about how the site works.
See the [contributing docs](contributing) for general information about working with the docs.

- [Frontmatter](#frontmatter)
- [`productVersions`](#productversions)
- [`versions`](#versions)
- [`redirect_from`](#redirect_from)
- [`title`](#title)
- [`shortTitle`](#shorttitle)
Expand Down Expand Up @@ -38,48 +38,39 @@ The following frontmatter values have special meanings and requirements for this
There's also a schema that's used by the test suite to validate every page's frontmatter.
See [`lib/frontmatter.js`](../lib/frontmatter.js).

### `productVersions`
### `versions`

- Purpose: Indicates the products and product versions to which a page applies.
- Purpose: Indicates the [versions](../lib/all-versions.js) to which a page applies.
See [Versioning](#versioning) for more info.
- Type: `Object`. Allowable keys map to product names and can be found in the `productVersions` object in [`lib/frontmatter.js`](../lib/frontmatter.js).
- Type: `Object`. Allowable keys map to product names and can be found in the `versions` object in [`lib/frontmatter.js`](../lib/frontmatter.js).
- This frontmatter value is currently **required** for all pages.
- The `*` is used to denote all releases for the version.

Example that applies to GitHub.com and recent versions of GitHub Enterprise:
Example that applies to GitHub.com and recent versions of GitHub Enterprise Server:

```yml
title: About your personal dashboard
productVersions:
dotcom: '*'
enterprise: '>=2.14'
versions:
free-pro-team: '*'
enterprise-server: '>=2.20'
```

Example that applies to all supported versions of GitHub enterprise
Example that applies to all supported versions of GitHub Enterprise Server:
(but not GitHub.com):

```yml
title: Downloading your license
productVersions:
enterprise: '*'
versions:
enterprise-server: '*'
```

Example that applies to GitHub Actions:

```yml
title: Building actions
productVersions:
actions: '*'
```

Note: Every product except `enterprise` is an evergreen product without specific versions, so the `*` is used to denote all versions.

### `redirect_from`

- Purpose: List URLs that should redirect to this page.
- Type: `Array` (for multiple redirects) or `String` (for just one)
- Type: `Array`
- Optional

Example with multiple redirects:
Example:

```yml
title: Getting started with GitHub Desktop
Expand All @@ -89,14 +80,7 @@ redirect_from:
- /articles/getting-started-with-github-for-windows/
```

Example with a single redirect:

```yml
title: Denying access to a previously approved OAuth App for your organization
redirect_from: /articles/denying-access-to-a-previously-approved-application-for-your-organization/
```

See [README#redirects](../README.md#redirects) for more info.
See [`contributing/redirects`](contributing/redirects.md) for more info.

### `title`

Expand All @@ -108,7 +92,7 @@ See [README#redirects](../README.md#redirects) for more info.

- Purpose: An abbreviated variant of the page title for use in breadcrumbs.
- Type: `String`
- Optional. If omitted, `title` will be used. Used only for map topic and category pages.
- Optional. If omitted, `title` will be used.

Example:

Expand Down Expand Up @@ -163,7 +147,7 @@ For a layout named `layouts/article.html`, the value would be `article`.
### `miniTocMaxHeadingLevel`

- Purpose: Indicates the maximum heading level to include in an article's mini TOC. See [Autogenerated mini TOCs](#autogenerated-mini-tocs) for more info.
- Type: `Number`. Default is `3`. Minimum is `2`. Maximum is `4` for now. (If we need to add more levels, we can revisit this. We will need to add CSS to do deeper nesting.)
- Type: `Number`. Default is `3`. Minimum is `2`. Maximum is `4`.
- Optional.

### `allowTitleToDifferFromFilename`
Expand Down Expand Up @@ -193,56 +177,16 @@ Make sure not to add hardcoded "In this article" sections in the Markdown source

## Versioning

Versioning for any content file lives in **two** places:

* The file's [`productVersions`](#productversions) frontmatter.
* Liquid conditionals in the file's parent [index page](#index-pages).

For example, an article with this frontmatter:

```yml
title: About your personal dashboard
productVersions:
dotcom: '*'
enterprise: '>=2.14'
```

should be referenced in the parent index page like this:
A content file can have **two** types of versioning:

```
{%- if page.version == 'dotcom' or page.version ver_gt "2.13" %}
- About your personal dashboard
{%- endif %}
```
* [`versions`](#versions) frontmatter (**required**)
* Determines in which the versions the page is available. See [contributing/permalinks](../contributing/permalinks.md) for more info.
* Liquid statements in content (**optional**)
* Conditionally render content depending on the current version being viewed. See [contributing/liquid-helpers](../contributing/liquid-helpers.md) for more info. Note Liquid conditionals can also appear in `data` and `include` files.

## Filenames

The site automatically creates links to articles in index pages. For example, this block in `content/index.md`:

```
## Bootcamp

- Set up git
- Create a repo
- Fork a repo
- Be social
```

renders with links to each article.

If you're adding a new article, make sure the filename is a [kebab-cased](https://en.wikipedia.org/wiki/Letter_case#Special_case_styles) version of the title you use in both the article and the parent index. This can get tricky when a title has punctuation (such as "GitHub's Billing Plans"). If you're not sure what the filename should be based on the title, you can find out by adding the title to the TOC. For example:

```
## Bootcamp

- Set up git
- Create a repo
- Fork a repo
- Be social
- I'm a new article
```

Then just run the site locally and see what the link is. In this example, the filename would be: `im-a-new-article`
When adding a new article, make sure the filename is a [kebab-cased](https://en.wikipedia.org/wiki/Letter_case#Special_case_styles) version of the title you use in the article's [`title`](#title) frontmatter. This can get tricky when a title has punctuation (such as "GitHub's Billing Plans"). A test will flag any discrepancies between title and filename. To override this requirement for a given article, you can add [`allowTitleToDifferFromFilename`](#allowtitletodifferfromfilename) frontmatter.

## Whitespace control

Expand All @@ -258,39 +202,39 @@ These characters are especially important in [index pages](#index-pages) compris

## Links and image paths

Any local links (like those starting with `/articles/`) and image paths (starting with `/assets`) that you include in content and data files will undergo some transformations on the server side to match the current page's language and Enterprise version (if applicable). The handling for these transformations lives in [`lib/rewrite-local-links`](lib/rewrite-local-links.js) and [`lib/rewrite-asset-paths-to-s3`](lib/rewrite-asset-paths-to-s3.js).
Local links must start with a product ID (like `/actions` or `/admin`), and image paths must start with `/assets`. These links undergo some transformations on the server side to match the current page's language and version. The handling for these transformations lives in [`lib/rewrite-local-links`](lib/rewrite-local-links.js) and [`lib/rewrite-asset-paths-to-s3`](lib/rewrite-asset-paths-to-s3.js).

For example, if you include the following link in a content file:

```
/articles/creating-a-saved-reply
/github/writing-on-github/creating-a-saved-reply
```
When viewed on Dotcom, the link gets rendered with the language code:
When viewed on GitHub.com docs, the link gets rendered with the language code and version:
```
/en/articles/creating-a-saved-reply
/en/free-pro-team@latest/github/writing-on-github/creating-a-saved-reply
```
and when viewed on GHE, the version is included as well:
and when viewed on GitHub Enterprise Server docs, the version is included as well:
```
/en/enterprise/2.16/user/articles/creating-a-saved-reply
/en/enterprise-server@2.20/github/writing-on-github/creating-a-saved-reply
```

The transformation is a little simpler for image paths. If you include the following image path in a content file:
The transformation is a little different for image paths. If you include the following image path in a content file:

```
/assets/images/help/profile/follow-user-button.png
```
when viewed on GHE, the path gets rewritten to include S3:
when viewed on GitHub Enterprise Server docs, the path gets rewritten to include S3:

```
https://github-images.s3.amazonaws.com/enterprise/2.16/assets/images/help/profile/follow-user-button.png
https://github-images.s3.amazonaws.com/enterprise/2.20/assets/images/help/profile/follow-user-button.png
```

### Preventing transformations

Sometimes you want to link to a Dotcom-only article in Enterprise content and you don't want the link to be Enterprise-ified. To prevent the transformation, write the link using HTML and add a class of `dotcom-only`. For example:

```
<a href="/articles/github-terms-of-service/" class="dotcom-only">GitHub's Terms of Service</a>
<a href="/github/site-policy/github-terms-of-service" class="dotcom-only">GitHub's Terms of Service</a>
```

Sometimes the canonical home of content moves outside the help site. None of the links included in [`lib/external-redirects.json`](lib/external-redirects.json) get rewritten. See the top-level [README](../README.md#external-redirects) for more info about this type of redirect.
Sometimes the canonical home of content moves outside the docs site. None of the links included in [`lib/redirects/external-redirects.json`](lib/redirects/external-redirects.json) get rewritten. See [`contributing/redirects.md`](contributing/redirects.md) for more info about this type of redirect.
45 changes: 23 additions & 22 deletions contributing/liquid-helpers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,13 +45,13 @@ Note: The below examples are only intended to show Liquid syntax and operators.
In statements where **all** operands must be true for the condition to be true, use the operator `and`:

```
{% if page.version != "dotcom" and page.version ver_gt "2.6" %}
{% if currentVersion != "free-pro-team@latest" and currentVersion ver_gt "enterprise-server@2.21" %}
```

In statements where **at least one** operand must be true for the condition to be true, use the operator `or`:

```
{% if page.version == "dotcom" or page.version ver_gt "2.6" %}
{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.21" %}
```

Do **not** use the operators `&&` or `||`. If you do, the content will not render in the intended versions. Only use `and` or `or`.
Expand All @@ -74,39 +74,39 @@ If your content is included in all versions of Enterprise, you need not include
If your content only applies to GitHub.com, such as billing information, use this logic:

```
{% if page.version == "dotcom" %}This is how you pay for your personal account, which is something you wouldn't do in Enterprise.{% endif %}
{% if currentVersion == "free-pro-team@latest" %}This is how you pay for your personal account, which is something you wouldn't do in Enterprise.{% endif %}
```

In this example:
- `if page.version == "dotcom"` will include the content for Dotcom output and *only* Dotcom.
- `if currentVersion == "free-pro-team@latest"` will include the content for Dotcom output and *only* Dotcom.
- `{% endif %}` ends the statement.

#### Including content for *new Dotcom features* that will be included in Enterprise

If your content is describing a new feature that was added to GitHub.com and will be automatically included in the next release of GitHub Enterprise, use this logic:

```
{% if page.version == "dotcom" or page.version ver_gt "2.6" %}This is a brand new feature, the likes of which have never been seen at this company before!{% endif %}
{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.21" %}This is a brand new feature, the likes of which have never been seen at this company before!{% endif %}
```

In this example:

- `if page.version == "dotcom"` will include the content for GitHub.com output.
- `or page.version ver_gt "2.6"` will include the content for releases *after* Enterprise 2.6, which means the content will be included for 2.7+.
- `if currentVersion == "free-pro-team@latest"` will include the content for GitHub.com output.
- `or currentVersion ver_gt "enterprise-server@2.21"` will include the content for releases *after* Enterprise 2.21, which means the content will be included for 2.7+.
- `{% endif %}` ends the statement.

#### Including content for *changed* Dotcom features that will also change in Enterprise

If your content is describing a change to existing functionality in Dotcom, such as changed UI text or a more simple means of completing a task, use this logic:

```
{% if page.version == "dotcom" or page.version ver_gt "2.10" %}This is the new way of doing things {% else %}This is the old way of doing things {% endif %}
{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "2.20" %}This is the new way of doing things {% else %}This is the old way of doing things {% endif %}
```

In this example:

- `if page.version == "dotcom"` will include the content for GitHub.com output.
- `or page.version ver_gt "2.6"` will include the content for releases *after* Enterprise 2.6, which means the content will be included for 2.7+.
- `if currentVersion == "free-pro-team@latest"` will include the content for GitHub.com output.
- `or currentVersion ver_gt "enterprise-server@2.21"` will include the content for releases *after* Enterprise 2.21, which means the content will be included for 2.22+.
- `{% else %}` means if the above is NOT true, then display the content that follows, `This is the old way of doing things`.
- `{% endif %}` ends the statement.

Expand All @@ -115,49 +115,50 @@ In this example:
If your content is describing a change to existing functionality in Dotcom, and that functionality doesn't exist in all older Enterprise versions, use logic like this:

```
{% if page.version == 'dotcom' or page.version ver_gt "2.10" %}
{% if currentVersion == 'dotcom' or currentVersion ver_gt "2.20" %}

This is the new way of doing things.

{% elsif page.version ver_gt "2.8" and page.version ver_lt "2.11" %}
{% endif %}
{% if currentVersion ver_gt "enterprise-server@2.19" and currentVersion ver_lt "2.21" %}

This is the old way of doing things (which did not exist before 2.9).
This is the old way of doing things (which did not exist before 2.20).

{% endif %}
```

In this example:

- `if page.version == "dotcom"` will include the content for GitHub.com output.
- `or page.version ver_gt "2.10"` will include the content for releases *after* Enterprise 2.10, which means the content will be included for 2.11+.
- `elsif page.version ver_gt "2.8" and page.version ver_lt "2.11"` means if the above is NOT true, and the version is either 2.9 or 2.10, then display the content that follows, `This is the old way of doing things`. No content will be displayed for versions older than 2.9.
- `if currentVersion == "free-pro-team@latest"` will include the content for GitHub.com output.
- `or currentVersion ver_gt "2.20"` will include the content for releases *after* Enterprise 2.20, which means the content will be included for 2.21+.
- `elsif currentVersion ver_gt "enterprise-server@2.19" and currentVersion ver_lt "2.21"` means if the above is NOT true, and the version is 2.20, then display the content that follows, `This is the old way of doing things`. No content will be displayed for versions older than 2.20.
- `{% endif %}` ends the statement.

#### Including content for *new Enterprise features* that don't exist on Dotcom

If your content is describing a new feature that was added to GitHub Enterprise but not GitHub, such as LDAP support, use this logic:

```
{% if page.version != "dotcom" and page.version ver_gt "2.6" %}This is a brand new feature, admin-type people!{% endif %}
{% if currentVersion != "free-pro-team@latest" and currentVersion ver_gt "enterprise-server@2.21" %}This is a brand new feature, admin-type people!{% endif %}
```

In this example:

- `if page.version != "dotcom"` will exclude the content for GitHub.com output.
- `and page.version ver_gt "2.6"` will *additionally* include the content for releases *after* Enterprise 2.6, which means the content will be included for 2.7+.
- `if currentVersion != "free-pro-team@latest"` will exclude the content for GitHub.com output.
- `and currentVersion ver_gt "enterprise-server@2.21"` will *additionally* include the content for releases *after* Enterprise 2.21, which means the content will be included for 2.22+.
- `{% endif %}` ends the statement.

#### Including content for *changed Enterprise features* that don't exist on Dotcom

If your content is describing a change to existing functionality in GitHub Enterprise, such as changed UI text or a more simple means of completing a task in the Management Console, use this logic:

```
{% if page.version != "dotcom" and page.version ver_gt "2.6" %}This is the new way of doing things, admins! {% else %}This is the old way of doing things, admins! {% endif %}
{% if currentVersion != "free-pro-team@latest" and currentVersion ver_gt "enterprise-server@2.21" %}This is the new way of doing things, admins! {% else %}This is the old way of doing things, admins! {% endif %}
```

In this example:

- `if page.version != "dotcom"` will exclude the content for GitHub.com output.
- `and page.version ver_gt "2.6"` will *additionally* include the content for releases *after* Enterprise 2.6, which means the content will be included for 2.7+.
- `if currentVersion != "free-pro-team@latest"` will exclude the content for GitHub.com output.
- `and currentVersion ver_gt "enterprise-server@2.21"` will *additionally* include the content for releases *after* Enterprise 2.21, which means the content will be included for 2.22+.
- `{% else %}` means if the above is NOT true, then display the content that follows, `This is the old way of doing things, admins!`.
- `{% endif %}` ends the statement.
18 changes: 9 additions & 9 deletions contributing/permalinks.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,15 @@
# Permalinks

Because the site is dynamic, it does not build HTML files for each different version of an article. Instead it generates a "permalink" for every version of the article. It does this based on the article's [`productVersions` frontmatter](content#productversions).
Because the site is dynamic, it does not build HTML files for each different version of an article. Instead it generates a "permalink" for every version of the article. It does this based on the article's [`versions` frontmatter](content#versions).

For example, an article that is available in Dotcom and all Enterprise versions will have permalinks like the following:
For example, an article that is available in currently supported versions will have permalink URLs like the following:

* `/en/articles/set-up-git`
* `/en/enterprise/2.16/user/articles/set-up-git`
* `/en/enterprise/2.15/user/articles/set-up-git`
* `/en/enterprise/2.14/user/articles/set-up-git`
* `/en/enterprise/2.13/user/articles/set-up-git`
* `/en/free-pro-team@latest/github/getting-started-with-github/set-up-git`
* `/en/enterprise-server@2.22/github/getting-started-with-github/set-up-git`
* `/en/enterprise-server@2.21/github/getting-started-with-github/set-up-git`
* `/en/enterprise-server@2.20/github/getting-started-with-github/set-up-git`
* `/en/enterprise-server@2.19/github/getting-started-with-github/set-up-git`

An article that is only available in Dotcom will have just one permalink:
An article that is not available in Enterprise will have just one permalink:

* `/en/articles/githubs-billing-plans`
* `/en/free-pro-team@latest/github/getting-started-with-github/set-up-git`
Loading