Make GitHub Pages content a top-level doc set (#18480)
* Add new product to products.yml * Move directory to new location * Update new index page * Remove old category from github product index * Add getting started category * Add Jekyll category * Create custom domain category * Update links to custom domain articles * Add redirects and update links for getting started articles * Add redirects and update links for jekyll articles * Fix link * Fix link * Fix link * Fix link
This commit is contained in:
Emily Gould
@@ -17,7 +17,7 @@ When you rename a repository, all existing information, with the exception of pr
|
||||
* Stars
|
||||
* Followers
|
||||
|
||||
For more information on project sites, see "[About {% data variables.product.prodname_pages %}](/github/working-with-github-pages/about-github-pages#types-of-github-pages-sites)."
|
||||
For more information on project sites, see "[About {% data variables.product.prodname_pages %}](/pages/getting-started-with-github-pages/about-github-pages#types-of-github-pages-sites)."
|
||||
|
||||
In addition to redirecting web traffic, all `git clone`, `git fetch`, or `git push` operations targeting the previous location will continue to function as if made on the new location. However, to reduce confusion, we strongly recommend updating any existing local clones to point to the new repository URL. You can do this by using `git remote` on the command line:
|
||||
|
||||
@@ -29,7 +29,7 @@ For more information, see "[Managing remote repositories](/github/getting-starte
|
||||
|
||||
{% if currentVersion == "free-pro-team@latest" %}
|
||||
|
||||
If you plan to rename a repository that has a {% data variables.product.prodname_pages %} site, we recommend using a custom domain for your site. This ensures that the site's URL isn't impacted by renaming the repository. For more information, see "[About custom domains and {% data variables.product.prodname_pages %} site](/github/working-with-github-pages/about-custom-domains-and-github-pages)."
|
||||
If you plan to rename a repository that has a {% data variables.product.prodname_pages %} site, we recommend using a custom domain for your site. This ensures that the site's URL isn't impacted by renaming the repository. For more information, see "[About custom domains and {% data variables.product.prodname_pages %} site](/pages/configuring-a-custom-domain-for-your-github-pages-site/about-custom-domains-and-github-pages)."
|
||||
|
||||
{% endif %}
|
||||
|
||||
|
||||
@@ -57,7 +57,6 @@ versions:
|
||||
|
||||
{% link_in_list /extending-github %}
|
||||
|
||||
{% link_in_list /working-with-github-pages %}
|
||||
{% link_in_list /supporting-the-open-source-community-with-github-sponsors %}
|
||||
{% link_in_list /finding-talent-with-github-jobs %}
|
||||
{% link_in_list /working-with-github-support %}
|
||||
|
||||
@@ -18,7 +18,7 @@ topics:
|
||||
If your organization uses {% data variables.product.prodname_ghe_cloud %}, you can choose to allow organization members to create publicly published sites, privately published sites, both, or neither. Otherwise, you can choose to allow or disallow public publishing. For more information about access control for {% data variables.product.prodname_pages %} sites, see "[Changing the visibility of your {% data variables.product.prodname_pages %} site](/github/working-with-github-pages/changing-the-visibility-of-your-github-pages-site)."
|
||||
{% endif %}
|
||||
|
||||
If you disallow publication of {% data variables.product.prodname_pages %} sites, any sites that are already published will remain published. You can manually unpublish the site. For more information, see "[Unpublishing a {% data variables.product.prodname_pages %} site](/github/working-with-github-pages/unpublishing-a-github-pages-site)."
|
||||
If you disallow publication of {% data variables.product.prodname_pages %} sites, any sites that are already published will remain published. You can manually unpublish the site. For more information, see "[Unpublishing a {% data variables.product.prodname_pages %} site](/pages/getting-started-with-github-pages/unpublishing-a-github-pages-site)."
|
||||
|
||||
{% data reusables.profile.access_profile %}
|
||||
{% data reusables.profile.access_org %}
|
||||
@@ -32,4 +32,4 @@ If you disallow publication of {% data variables.product.prodname_pages %} sites
|
||||
|
||||
### Further reading
|
||||
|
||||
- "[About {% data variables.product.prodname_pages %}](/github/working-with-github-pages/about-github-pages)"
|
||||
- "[About {% data variables.product.prodname_pages %}](/pages/getting-started-with-github-pages/about-github-pages)"
|
||||
|
||||
@@ -25,7 +25,7 @@ Commits will appear on your contributions graph if they meet **all** of the foll
|
||||
- In the repository's default branch
|
||||
- In the `gh-pages` branch (for repositories with project sites)
|
||||
|
||||
For more information on project sites, see "[About {% data variables.product.prodname_pages %}](/github/working-with-github-pages/about-github-pages#types-of-github-pages-sites)."
|
||||
For more information on project sites, see "[About {% data variables.product.prodname_pages %}](/pages/getting-started-with-github-pages/about-github-pages#types-of-github-pages-sites)."
|
||||
|
||||
In addition, **at least one** of the following must be true:
|
||||
- You are a collaborator on the repository or are a member of the organization that owns the repository.
|
||||
@@ -66,7 +66,7 @@ Generic email addresses--such as `jane@computer.local`--cannot be added to {% da
|
||||
|
||||
#### Commit was not made in the default or `gh-pages` branch
|
||||
|
||||
Commits are only counted if they are made in the default branch or the `gh-pages` branch (for repositories with project sites). For more information, see "[About {% data variables.product.prodname_pages %}](/github/working-with-github-pages/about-github-pages#types-of-github-pages-sites)."
|
||||
Commits are only counted if they are made in the default branch or the `gh-pages` branch (for repositories with project sites). For more information, see "[About {% data variables.product.prodname_pages %}](/pages/getting-started-with-github-pages/about-github-pages#types-of-github-pages-sites)."
|
||||
|
||||
If your commits are in a non-default or non-`gh-pages` branch and you'd like them to count toward your contributions, you will need to do one of the following:
|
||||
- [Open a pull request](/articles/creating-a-pull-request) to have your changes merged into the default branch or the `gh-pages` branch.
|
||||
|
||||
@@ -1,65 +0,0 @@
|
||||
---
|
||||
title: About custom domains and GitHub Pages
|
||||
intro: '{% data variables.product.prodname_pages %} supports using custom domains, or changing the root of your site''s URL from the default, like `octocat.github.io`, to any domain you own.'
|
||||
redirect_from:
|
||||
- /articles/about-custom-domains-for-github-pages-sites/
|
||||
- /articles/about-supported-custom-domains/
|
||||
- /articles/custom-domain-redirects-for-your-github-pages-site/
|
||||
- /articles/about-custom-domains-and-github-pages
|
||||
product: '{% data reusables.gated-features.pages %}'
|
||||
versions:
|
||||
free-pro-team: '*'
|
||||
topics:
|
||||
- pages
|
||||
---
|
||||
|
||||
### Supported custom domains
|
||||
|
||||
{% data variables.product.prodname_pages %} works with two types of domains: subdomains and apex domains. For a list of unsupported custom domains, see "[Troubleshooting custom domains and {% data variables.product.prodname_pages %}](/articles/troubleshooting-custom-domains-and-github-pages/#custom-domain-names-that-are-unsupported)."
|
||||
|
||||
| Supported custom domain type | Example |
|
||||
|---|---|
|
||||
| `www` subdomain | `www.example.com` |
|
||||
| Custom subdomain | `blog.example.com` |
|
||||
| Apex domain | `example.com` |
|
||||
|
||||
You can set up either or both types of custom domains for your site. We recommend always using a `www` subdomain, even if you also use an apex domain. For more information, see "[Using an apex domain for your {% data variables.product.prodname_pages %} site](#using-an-apex-domain-for-your-github-pages-site)."
|
||||
|
||||
After you configure a custom domain for a user or organization site, the custom domain will replace the `<user>.github.io` or `<organization>.github.io` portion of the URL for any project sites owned by the account that do not have a custom domain configured. For example, if the custom domain for your user site is `www.octocat.com`, and you have a project site with no custom domain configured that is published from a repository called `octo-project`, the {% data variables.product.prodname_pages %} site for that repository will be available at `www.octocat.com/octo-project`.
|
||||
|
||||
### Using a subdomain for your {% data variables.product.prodname_pages %} site
|
||||
|
||||
A subdomain is the part of a URL before the root domain. You can configure your subdomain as `www` or as a distinct section of your site, like `blog.example.com`.
|
||||
|
||||
Subdomains are configured with a `CNAME` record through your DNS provider. For more information, see "[Managing a custom domain for your {% data variables.product.prodname_pages %} site](/articles/managing-a-custom-domain-for-your-github-pages-site#configuring-a-subdomain)."
|
||||
|
||||
#### `www` subdomains
|
||||
|
||||
A `www` subdomain is the most commonly used type of subdomain. For example, `www.example.com` includes a `www` subdomain.
|
||||
|
||||
`www` subdomains are the most stable type of custom domain because `www` subdomains are not affected by changes to the IP addresses of {% data variables.product.product_name %}'s servers. Your site will also load faster because Denial of Service (DoS) attack protection can be implemented more efficiently.
|
||||
|
||||
#### Custom subdomains
|
||||
|
||||
A custom subdomain is a type of subdomain that doesn't use the standard `www` subdomain. Custom subdomains are mostly used when you want two distinct sections of your site. For example, you can create a site called `blog.example.com` and customize that section independently from `www.example.com`.
|
||||
|
||||
### Using an apex domain for your {% data variables.product.prodname_pages %} site
|
||||
|
||||
An apex domain is a custom domain that does not contain a subdomain, such as `example.com`. Apex domains are also known as base, bare, naked, root apex, or zone apex domains.
|
||||
|
||||
An apex domain is configured with an `A`, `ALIAS`, or `ANAME` record through your DNS provider. For more information, see "[Managing a custom domain for your {% data variables.product.prodname_pages %} site](/articles/managing-a-custom-domain-for-your-github-pages-site#configuring-an-apex-domain)."
|
||||
|
||||
{% data reusables.pages.www-and-apex-domain-recommendation %} For more information, see "[Managing a custom domain for your {% data variables.product.prodname_pages %} site](/github/working-with-github-pages/managing-a-custom-domain-for-your-github-pages-site/#configuring-a-subdomain)."
|
||||
|
||||
### Updating custom domains when your {% data variables.product.prodname_pages %} site is disabled
|
||||
|
||||
If your {% data variables.product.prodname_pages %} site is disabled but has a custom domain set up, you should immediately update or remove your DNS records with your DNS provider to avoid the risk of a domain takeover. Having a custom domain configured with your DNS provider while your site is disabled could result in someone else hosting a site on one of your subdomains. For more information, see "[Managing a custom domain for your {% data variables.product.prodname_pages %} site](/articles/managing-a-custom-domain-for-your-github-pages-site)."
|
||||
|
||||
There are a couple of reasons your site might be automatically disabled.
|
||||
|
||||
- If you downgrade from {% data variables.product.prodname_pro %} to {% data variables.product.prodname_free_user %}, any {% data variables.product.prodname_pages %} sites that are currently published from private repositories in your account will be unpublished. For more information, see "[Downgrading your {% data variables.product.prodname_dotcom %} billing plan](/articles/downgrading-your-github-billing-plan)."
|
||||
- If you transfer a private repository to a personal account that is using {% data variables.product.prodname_free_user %}, the repository will lose access to the {% data variables.product.prodname_pages %} feature, and the currently published {% data variables.product.prodname_pages %} site will be unpublished. For more information, see "[Transferring a repository](/articles/transferring-a-repository)."
|
||||
|
||||
### Further reading
|
||||
|
||||
- "[Troubleshooting custom domains and {% data variables.product.prodname_pages %}](/articles/troubleshooting-custom-domains-and-github-pages)"
|
||||
@@ -1,130 +0,0 @@
|
||||
---
|
||||
title: About GitHub Pages and Jekyll
|
||||
intro: 'Jekyll is a static site generator with built-in support for {% data variables.product.prodname_pages %}.'
|
||||
redirect_from:
|
||||
- /articles/about-jekyll-themes-on-github
|
||||
- /articles/configuring-jekyll
|
||||
- /articles/configuring-jekyll-plugins
|
||||
- /articles/using-syntax-highlighting-on-github-pages
|
||||
- /articles/files-that-start-with-an-underscore-are-missing
|
||||
- /articles/sitemaps-for-github-pages/
|
||||
- /articles/search-engine-optimization-for-github-pages/
|
||||
- /articles/repository-metadata-on-github-pages/
|
||||
- /articles/atom-rss-feeds-for-github-pages/
|
||||
- /articles/redirects-on-github-pages/
|
||||
- /articles/emoji-on-github-pages/
|
||||
- /articles/mentions-on-github-pages/
|
||||
- /articles/using-jekyll-plugins-with-github-pages/
|
||||
- /articles/adding-jekyll-plugins-to-a-github-pages-site/
|
||||
- /articles/about-github-pages-and-jekyll
|
||||
product: '{% data reusables.gated-features.pages %}'
|
||||
versions:
|
||||
free-pro-team: '*'
|
||||
enterprise-server: '*'
|
||||
github-ae: '*'
|
||||
topics:
|
||||
- pages
|
||||
---
|
||||
|
||||
### About Jekyll
|
||||
|
||||
Jekyll is a static site generator with built-in support for {% data variables.product.prodname_pages %} and a simplified build process. Jekyll takes Markdown and HTML files and creates a complete static website based on your choice of layouts. Jekyll supports Markdown and Liquid, a templating language that loads dynamic content on your site. For more information, see [Jekyll](https://jekyllrb.com/).
|
||||
|
||||
Jekyll is not officially supported for Windows. For more information, see "[Jekyll on Windows](http://jekyllrb.com/docs/windows/#installation)" in the Jekyll documentation.
|
||||
|
||||
We recommend using Jekyll with {% data variables.product.prodname_pages %}. If you prefer, you can use other static site generators or customize your own build process locally or on another server. For more information, see "[About {% data variables.product.prodname_pages %}](/articles/about-github-pages#static-site-generators)."
|
||||
|
||||
### Configuring Jekyll in your {% data variables.product.prodname_pages %} site
|
||||
|
||||
You can configure most Jekyll settings, such as your site's theme and plugins, by editing your *_config.yml* file. For more information, see "[Configuration](https://jekyllrb.com/docs/configuration/)" in the Jekyll documentation.
|
||||
|
||||
Some configuration settings cannot be changed for {% data variables.product.prodname_pages %} sites.
|
||||
|
||||
```yaml
|
||||
lsi: false
|
||||
safe: true
|
||||
source: [your repo's top level directory]
|
||||
incremental: false
|
||||
highlighter: rouge
|
||||
gist:
|
||||
noscript: false
|
||||
kramdown:
|
||||
math_engine: mathjax
|
||||
syntax_highlighter: rouge
|
||||
```
|
||||
|
||||
By default, Jekyll doesn't build files or folders that:
|
||||
- are located in a folder called `/node_modules` or `/vendor`
|
||||
- start with `_`, `.`, or `#`
|
||||
- end with `~`
|
||||
- are excluded by the `exclude` setting in your configuration file
|
||||
|
||||
If you want Jekyll to process any of these files, you can use the `includes` setting in your configuration file.
|
||||
|
||||
### Front matter
|
||||
|
||||
{% data reusables.pages.about-front-matter %}
|
||||
|
||||
You can add `site.github` to a post or page to add any repository references metadata to your site. For more information, see "[Using `site.github`](https://jekyll.github.io/github-metadata/site.github/)" in the Jekyll Metadata documentation.
|
||||
|
||||
### Themes
|
||||
|
||||
{% data reusables.pages.add-jekyll-theme %} For more information, see "[Themes](https://jekyllrb.com/docs/themes/)" in the Jekyll documentation.
|
||||
|
||||
{% if currentVersion == "free-pro-team@latest" %}
|
||||
You can add a supported theme to your site on {% data variables.product.prodname_dotcom %}. For more information, see "[Supported themes](https://pages.github.com/themes/)" on the {% data variables.product.prodname_pages %} site and "[Adding a theme to your {% data variables.product.prodname_pages %} site with the theme chooser](/articles/adding-a-theme-to-your-github-pages-site-with-the-theme-chooser)."
|
||||
|
||||
To use any other open source Jekyll theme hosted on {% data variables.product.prodname_dotcom %}, you can add the theme manually.{% else %} You can add a theme to your site manually.{% endif %} For more information, see{% if currentVersion == "free-pro-team@latest" %} [themes hosted on {% data variables.product.prodname_dotcom %}](https://github.com/topics/jekyll-theme) and{% else %} "[Supported themes](https://pages.github.com/themes/)" on the {% data variables.product.prodname_pages %} site and{% endif %} "[Adding a theme to your {% data variables.product.prodname_pages %} site using Jekyll](/articles/adding-a-theme-to-your-github-pages-site-using-jekyll)."
|
||||
|
||||
You can override any of your theme's defaults by editing the theme's files. For more information, see your theme's documentation and "[Overriding your theme's defaults](https://jekyllrb.com/docs/themes/#overriding-theme-defaults)" in the Jekyll documentation.
|
||||
|
||||
### Plugins
|
||||
|
||||
You can download or create Jekyll plugins to extend the functionality of Jekyll for your site. For example, the [jemoji](https://github.com/jekyll/jemoji) plugin lets you use {% data variables.product.prodname_dotcom %}-flavored emoji in any page on your site the same way you would on {% data variables.product.prodname_dotcom %}. For more information, see "[Plugins](https://jekyllrb.com/docs/plugins/)" in the Jekyll documentation.
|
||||
|
||||
{% data variables.product.prodname_pages %} uses plugins that are enabled by default and cannot be disabled:
|
||||
- [`jekyll-coffeescript`](https://github.com/jekyll/jekyll-coffeescript)
|
||||
- [`jekyll-default-layout`](https://github.com/benbalter/jekyll-default-layout)
|
||||
- [`jekyll-gist`](https://github.com/jekyll/jekyll-gist)
|
||||
- [`jekyll-github-metadata`](https://github.com/jekyll/github-metadata)
|
||||
- [`jekyll-optional-front-matter`](https://github.com/benbalter/jekyll-optional-front-matter)
|
||||
- [`jekyll-paginate`](https://github.com/jekyll/jekyll-paginate)
|
||||
- [`jekyll-readme-index`](https://github.com/benbalter/jekyll-readme-index)
|
||||
- [`jekyll-titles-from-headings`](https://github.com/benbalter/jekyll-titles-from-headings)
|
||||
- [`jekyll-relative-links`](https://github.com/benbalter/jekyll-relative-links)
|
||||
|
||||
You can enable additional plugins by adding the plugin's gem to the `plugins` setting in your *_config.yml* file. For more information, see "[Configuration](https://jekyllrb.com/docs/configuration/)" in the Jekyll documentation.
|
||||
|
||||
For a list of supported plugins, see "[Dependency versions](https://pages.github.com/versions/)" on the {% data variables.product.prodname_pages %} site. For usage information for a specific plugin, see the plugin's documentation.
|
||||
|
||||
{% tip %}
|
||||
|
||||
**Tip:** You can make sure you're using the latest version of all plugins by keeping the {% data variables.product.prodname_pages %} gem updated. For more information, see "[Testing your GitHub Pages site locally with Jekyll](/articles/testing-your-github-pages-site-locally-with-jekyll#updating-the-github-pages-gem)" and "[Dependency versions](https://pages.github.com/versions/)" on the {% data variables.product.prodname_pages %} site.
|
||||
|
||||
{% endtip %}
|
||||
|
||||
{% data variables.product.prodname_pages %} cannot build sites using unsupported plugins. If you want to use unsupported plugins, generate your site locally and then push your site's static files to {% data variables.product.product_name %}.
|
||||
|
||||
### Syntax highlighting
|
||||
|
||||
To make your site easier to read, code snippets are highlighted on {% data variables.product.prodname_pages %} sites the same way they're highlighted on {% data variables.product.product_name %}. For more information about syntax highlighting on {% data variables.product.product_name %}, see "[Creating and highlighting code blocks](/articles/creating-and-highlighting-code-blocks)."
|
||||
|
||||
By default, code blocks on your site will be highlighted by Jekyll. Jekyll uses the [Rouge](https://github.com/jneen/rouge) highlighter, which is compatible with [Pygments](http://pygments.org/). If you specify Pygments in your *_config.yml* file, Rouge will be used instead. Jekyll cannot use any other syntax highlighter, and you'll get a page build warning if you specify another syntax highlighter in your *_config.yml* file. For more information, see "[About Jekyll build errors for {% data variables.product.prodname_pages %} sites](/articles/about-jekyll-build-errors-for-github-pages-sites)."
|
||||
|
||||
If you want to use another highlighter, such as `highlight.js`, you must disable Jekyll's syntax highlighting by updating your project's *_config.yml* file.
|
||||
|
||||
```yaml
|
||||
kramdown:
|
||||
syntax_highlighter_opts:
|
||||
disable : true
|
||||
```
|
||||
|
||||
If your theme doesn't include CSS for syntax highlighting, you can generate {% data variables.product.prodname_dotcom %}'s syntax highlighting CSS and add it to your project's `style.css` file.
|
||||
|
||||
```shell
|
||||
$ rougify style github > style.css
|
||||
```
|
||||
|
||||
### Building your site locally
|
||||
|
||||
{% data reusables.pages.test-locally %}
|
||||
@@ -1,149 +0,0 @@
|
||||
---
|
||||
title: About GitHub Pages
|
||||
intro: 'You can use {% data variables.product.prodname_pages %} to host a website about yourself, your organization, or your project directly from a {% data variables.product.product_name %} repository.'
|
||||
redirect_from:
|
||||
- /articles/what-are-github-pages/
|
||||
- /articles/what-is-github-pages/
|
||||
- /articles/user-organization-and-project-pages/
|
||||
- /articles/using-a-static-site-generator-other-than-jekyll/
|
||||
- /articles/mime-types-on-github-pages/
|
||||
- /articles/should-i-rename-usernamegithubcom-repositories-to-usernamegithubio/
|
||||
- /articles/about-github-pages
|
||||
product: '{% data reusables.gated-features.pages %}'
|
||||
versions:
|
||||
free-pro-team: '*'
|
||||
enterprise-server: '*'
|
||||
github-ae: '*'
|
||||
topics:
|
||||
- pages
|
||||
---
|
||||
|
||||
### About {% data variables.product.prodname_pages %}
|
||||
|
||||
{% data variables.product.prodname_pages %} is a static site hosting service that takes HTML, CSS, and JavaScript files straight from a repository on {% data variables.product.product_name %}, optionally runs the files through a build process, and publishes a website. You can see examples of {% data variables.product.prodname_pages %} sites in the [{% data variables.product.prodname_pages %} examples collection](https://github.com/collections/github-pages-examples).
|
||||
|
||||
{% if currentVersion == "free-pro-team@latest" %}
|
||||
You can host your site on {% data variables.product.prodname_dotcom %}'s `github.io` domain or your own custom domain. For more information, see "[Using a custom domain with {% data variables.product.prodname_pages %}](/articles/using-a-custom-domain-with-github-pages)."
|
||||
{% endif %}
|
||||
|
||||
{% if currentVersion == "free-pro-team@latest" %}
|
||||
{% data reusables.pages.about-private-publishing %} For more information, see "[Changing the visibility of your {% data variables.product.prodname_pages %} site](/github/working-with-github-pages/changing-the-visibility-of-your-github-pages-site)."
|
||||
{% endif %}
|
||||
|
||||
To get started, see "[Creating a {% data variables.product.prodname_pages %} site](/articles/creating-a-github-pages-site)."
|
||||
|
||||
{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %}
|
||||
Organization owners can disable the publication of {% data variables.product.prodname_pages %} sites from the organization's repositories. For more information, see "[Managing the publication of {% data variables.product.prodname_pages %} sites for your organization](/github/setting-up-and-managing-organizations-and-teams/managing-the-publication-of-github-pages-sites-for-your-organization)."
|
||||
{% endif %}
|
||||
|
||||
### Types of {% data variables.product.prodname_pages %} sites
|
||||
|
||||
There are three types of {% data variables.product.prodname_pages %} sites: project, user, and organization. Project sites are connected to a specific project hosted on {% data variables.product.product_name %}, such as a JavaScript library or a recipe collection. User and organization sites are connected to a specific {% data variables.product.product_name %} account.
|
||||
|
||||
To publish a user site, you must create a repository owned by your user account that's named {% if currentVersion == "free-pro-team@latest" %}`<username>.github.io`{% else %}`<username>.<hostname>`{% endif %}. To publish an organization site, you must create a repository owned by an organization that's named {% if currentVersion == "free-pro-team@latest" %}`<organization>.github.io`{% else %}`<organization>.<hostname>`{% endif %}. {% if currentVersion == "free-pro-team@latest" %}Unless you're using a custom domain, user and organization sites are available at `http(s)://<username>.github.io` or `http(s)://<organization>.github.io`.{% elsif currentVersion == "github-ae@latest" %}User and organization sites are available at `http(s)://pages.<hostname>/<username>` or `http(s)://pages.<hostname>/<organization>`.{% endif %}
|
||||
|
||||
The source files for a project site are stored in the same repository as their project. {% if currentVersion == "free-pro-team@latest" %}Unless you're using a custom domain, project sites are available at `http(s)://<username>.github.io/<repository>` or `http(s)://<organization>.github.io/<repository>`.{% elsif currentVersion == "github-ae@latest" %}Project sites are available at `http(s)://pages.<hostname>/<username>/<repository>/` or `http(s)://pages.<hostname>/<organization>/<repository>/`.{% endif %}
|
||||
|
||||
{% if currentVersion == "free-pro-team@latest" %}
|
||||
If you publish your site privately, the URL for your site will be different. For more information, see "[Changing the visibility of your {% data variables.product.prodname_pages %} site](/github/working-with-github-pages/changing-the-visibility-of-your-github-pages-site)."
|
||||
{% endif %}
|
||||
|
||||
{% if currentVersion == "free-pro-team@latest" %}
|
||||
For more information about how custom domains affect the URL for your site, see "[About custom domains and {% data variables.product.prodname_pages %}](/articles/about-custom-domains-and-github-pages)."
|
||||
{% endif %}
|
||||
|
||||
You can only create one user or organization site for each account on {% data variables.product.product_name %}. Project sites, whether owned by an organization or a user account, are unlimited.
|
||||
|
||||
{% if enterpriseServerVersions contains currentVersion %}
|
||||
The URL where your site is available depends on whether subdomain isolation is enabled for {% data variables.product.product_location %}.
|
||||
|
||||
| Type of site | Subdomain isolation enabled | Subdomain isolation disabled |
|
||||
| ------------ | --------------------------- | ---------------------------- |
|
||||
User | `http(s)://pages.<hostname>/<username>` | `http(s)://<hostname>/pages/<username>` |
|
||||
Organization | `http(s)://pages.<hostname>/<organization>` | `http(s)://<hostname>/pages/<organization>` |
|
||||
Project site owned by user account | `http(s)://pages.<hostname>/<username>/<repository>/` | `http(s)://<hostname>/pages/<username>/<repository>/`
|
||||
Project site owned by organization account | `http(s)://pages.<hostname>/<orgname>/<repository>/` | `http(s)://<hostname>/pages/<orgname>/<repository>/`
|
||||
|
||||
For more information, see "[Enabling subdomain isolation](/enterprise/{{ currentVersion }}/admin/installation/enabling-subdomain-isolation)" or contact your site administrator.
|
||||
{% endif %}
|
||||
|
||||
{% if currentVersion == "free-pro-team@latest" %}
|
||||
{% note %}
|
||||
|
||||
**Note:** Repositories using the legacy `<username>.github.com` naming scheme will still be published, but visitors will be redirected from `http(s)://<username>.github.com` to `http(s)://<username>.github.io`. If both a `<username>.github.com` and `<username>.github.io` repository exist, only the `<username>.github.io` repository will be published.
|
||||
|
||||
{% endnote %}
|
||||
{% endif %}
|
||||
|
||||
### Publishing sources for {% data variables.product.prodname_pages %} sites
|
||||
|
||||
The publishing source for your {% data variables.product.prodname_pages %} site is the branch and folder where the source files for your site are stored.
|
||||
|
||||
{% data reusables.pages.private_pages_are_public_warning %}
|
||||
|
||||
{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.22" or currentVersion == "github-ae@latest" %}
|
||||
|
||||
If the default publishing source exists in your repository, {% data variables.product.prodname_pages %} will automatically publish a site from that source. The default publishing source for user and organization sites is the root of the default branch for the repository. The default publishing source for project sites is the root of the `gh-pages` branch.
|
||||
|
||||
If you want to keep the source files for your site in a different location, you can change the publishing source for your site. You can publish your site from any branch in the repository, either from the root of the repository on that branch, `/`, or from the `/docs` folder on that branch. For more information, see "[Configuring a publishing source for your {% data variables.product.prodname_pages %} site](/articles/configuring-a-publishing-source-for-your-github-pages-site#choosing-a-publishing-source)."
|
||||
|
||||
If you choose the `/docs` folder of any branch as your publishing source, {% data variables.product.prodname_pages %} will read everything to publish your site{% if currentVersion == "free-pro-team@latest" %}, including the _CNAME_ file,{% endif %} from the `/docs` folder.{% if currentVersion == "free-pro-team@latest" %} For example, when you edit your custom domain through the {% data variables.product.prodname_pages %} settings, the custom domain will write to `/docs/CNAME`. For more information about _CNAME_ files, see "[Managing a custom domain for your {% data variables.product.prodname_pages %} site](/articles/managing-a-custom-domain-for-your-github-pages-site)."{% endif %}
|
||||
|
||||
{% else %}
|
||||
|
||||
The default publishing source for user and organization sites is the `master` branch. If the repository for your user or organization site has a `master` branch, your site will publish automatically from that branch. You cannot choose a different publishing source for user or organization sites.
|
||||
|
||||
The default publishing source for a project site is the `gh-pages` branch. If the repository for your project site has a `gh-pages` branch, your site will publish automatically from that branch.
|
||||
|
||||
Project sites can also be published from the `master` branch or a `/docs` folder on the `master` branch. To publish your site from one of these sources, you must configure a different publishing source. For more information, see "[Configuring a publishing source for your {% data variables.product.prodname_pages %} site](/articles/configuring-a-publishing-source-for-your-github-pages-site#choosing-a-publishing-source)."
|
||||
|
||||
If you choose the `/docs` folder of the `master` branch as your publishing source, {% data variables.product.prodname_pages %} will read everything to publish your site{% if currentVersion == "free-pro-team@latest" %}, including the _CNAME_ file,{% endif %} from the `/docs` folder.{% if currentVersion == "free-pro-team@latest" %} For example, when you edit your custom domain through the {% data variables.product.prodname_pages %} settings, the custom domain will write to `/docs/CNAME`. For more information about _CNAME_ files, see "[Managing a custom domain for your {% data variables.product.prodname_pages %} site](/articles/managing-a-custom-domain-for-your-github-pages-site)."{% endif %}
|
||||
|
||||
You cannot publish your project site from any other branch, even if the default branch is not `master` or `gh-pages`.
|
||||
|
||||
{% endif %}
|
||||
|
||||
### Static site generators
|
||||
|
||||
{% data variables.product.prodname_pages %} publishes any static files that you push to your repository. You can create your own static files or use a static site generator to build your site for you. You can also customize your own build process locally or on another server. We recommend Jekyll, a static site generator with built-in support for {% data variables.product.prodname_pages %} and a simplified build process. For more information, see "[About {% data variables.product.prodname_pages %} and Jekyll](/articles/about-github-pages-and-jekyll)."
|
||||
|
||||
{% data variables.product.prodname_pages %} will use Jekyll to build your site by default. If you want to use a static site generator other than Jekyll, disable the Jekyll build process by creating an empty file called `.nojekyll` in the root of your publishing source, then follow your static site generator's instructions to build your site locally.
|
||||
|
||||
{% data variables.product.prodname_pages %} does not support server-side languages such as PHP, Ruby, or Python.
|
||||
|
||||
### Guidelines for using {% data variables.product.prodname_pages %}
|
||||
|
||||
{% if currentVersion == "free-pro-team@latest" %}
|
||||
- {% data variables.product.prodname_pages %} sites created after June 15, 2016 and using `github.io` domains are served over HTTPS. If you created your site before June 15, 2016, you can enable HTTPS support for traffic to your site. For more information, see "[Securing your {% data variables.product.prodname_pages %} with HTTPS](/articles/securing-your-github-pages-site-with-https)."
|
||||
- {% data reusables.pages.no_sensitive_data_pages %}
|
||||
- Your use of {% data variables.product.prodname_pages %} is subject to the [GitHub Terms of Service](/articles/github-terms-of-service/), including the prohibition on reselling.
|
||||
|
||||
#### Usage limits
|
||||
{% endif %}
|
||||
{% data variables.product.prodname_pages %} sites are subject to the following usage limits:
|
||||
|
||||
- {% data variables.product.prodname_pages %} source repositories have a recommended limit of 1GB.{% if currentVersion == "free-pro-team@latest" %} For more information, see "[What is my disk quota?"](/articles/what-is-my-disk-quota/#file-and-repository-size-limitations){% endif %}
|
||||
- Published {% data variables.product.prodname_pages %} sites may be no larger than 1 GB.
|
||||
{% if currentVersion == "free-pro-team@latest" %}
|
||||
- {% data variables.product.prodname_pages %} sites have a *soft* bandwidth limit of 100GB per month.
|
||||
- {% data variables.product.prodname_pages %} sites have a *soft* limit of 10 builds per hour.
|
||||
|
||||
If your site exceeds these usage quotas, we may not be able to serve your site, or you may receive a polite email from {% data variables.contact.contact_support %} suggesting strategies for reducing your site's impact on our servers, including putting a third-party content distribution network (CDN) in front of your site, making use of other {% data variables.product.prodname_dotcom %} features such as releases, or moving to a different hosting service that might better fit your needs.
|
||||
|
||||
#### Prohibited uses
|
||||
|
||||
{% data variables.product.prodname_pages %} is not intended for or allowed to be used as a free web hosting service to run your online business, e-commerce site, or any other website that is primarily directed at either facilitating commercial transactions or providing commercial software as a service (SaaS).
|
||||
|
||||
In addition, {% data variables.product.prodname_dotcom %} does not allow {% data variables.product.prodname_pages %} to be used for certain purposes or activities. For a list of prohibited uses, see "[{% data variables.product.prodname_dotcom %}'s Additional Product Terms for {% data variables.product.prodname_pages %}](/github/site-policy/github-additional-product-terms#4-pages)."
|
||||
{% endif %}
|
||||
|
||||
### MIME types on {% data variables.product.prodname_pages %}
|
||||
|
||||
A MIME type is a header that a server sends to a browser, providing information about the nature and format of the files the browser requested. {% data variables.product.prodname_pages %} supports more than 750 MIME types across thousands of file extensions. The list of supported MIME types is generated from the [mime-db project](https://github.com/jshttp/mime-db).
|
||||
|
||||
While you can't specify custom MIME types on a per-file or per-repository basis, you can add or modify MIME types for use on {% data variables.product.prodname_pages %}. For more information, see [the mime-db contributing guidelines](https://github.com/jshttp/mime-db#adding-custom-media-types).
|
||||
|
||||
### Further reading
|
||||
|
||||
- [{% data variables.product.prodname_pages %}](https://lab.github.com/githubtraining/github-pages) on {% data variables.product.prodname_learning %}
|
||||
- "[{% data variables.product.prodname_pages %}](/rest/reference/repos#pages)"
|
||||
@@ -1,61 +0,0 @@
|
||||
---
|
||||
title: About Jekyll build errors for GitHub Pages sites
|
||||
intro: 'If Jekyll encounters an error building your {% data variables.product.prodname_pages %} site locally or on {% data variables.product.product_name %}, you''ll receive an error message with more information.'
|
||||
redirect_from:
|
||||
- /articles/viewing-jekyll-build-error-messages/
|
||||
- /articles/generic-jekyll-build-failures/
|
||||
- /articles/about-jekyll-build-errors-for-github-pages-sites
|
||||
product: '{% data reusables.gated-features.pages %}'
|
||||
versions:
|
||||
free-pro-team: '*'
|
||||
enterprise-server: '*'
|
||||
github-ae: '*'
|
||||
topics:
|
||||
- pages
|
||||
---
|
||||
|
||||
### About Jekyll build errors
|
||||
|
||||
Sometimes, {% data variables.product.prodname_pages %} will not attempt to build your site after you push changes to your site's publishing source.{% if currentVersion == "free-pro-team@latest" %}
|
||||
- The person who pushed the changes hasn't verified their email address. For more information, see "[Verifying your email address](/articles/verifying-your-email-address)."{% endif %}
|
||||
- You're pushing with a deploy key. If you want to automate pushes to your site's repository, you can set up a machine user instead. For more information, see "[Managing deploy keys](/developers/overview/managing-deploy-keys#machine-users)."
|
||||
- You're using a CI service that isn't configured to build your publishing source. For example, Travis CI won't build the `gh-pages` branch unless you add the branch to a safe list. For more information, see "[Customizing the build](https://docs.travis-ci.com/user/customizing-the-build/#safelisting-or-blocklisting-branches)" on Travis CI, or your CI service's documentation.
|
||||
|
||||
{% note %}
|
||||
|
||||
**Note:** It can take up to 20 minutes for changes to your site to publish after you push the changes to {% data variables.product.product_name %}.
|
||||
|
||||
{% endnote %}
|
||||
|
||||
If Jekyll does attempt to build your site and encounters an error, you will receive a build error message. There are two main types of Jekyll build error messages.
|
||||
- A "Page build warning" message means your build completed successfully, but you may need to make changes to prevent future problems.
|
||||
- A "Page build failed" message means your build failed to complete. If Jekyll is able to detect a reason for the failure, you'll see a descriptive error message.
|
||||
|
||||
For more information about troubleshooting build errors, see "[Troubleshooting Jekyll build errors for {% data variables.product.prodname_pages %} sites](/articles/troubleshooting-jekyll-build-errors-for-github-pages-sites)."
|
||||
|
||||
### Viewing Jekyll build error messages
|
||||
|
||||
We recommend testing your site locally, which allows you to see build error messages on the command line, and addressing any build failures before pushing changes to {% data variables.product.product_name %}. For more information, see "[Testing your {% data variables.product.prodname_pages %} site locally with Jekyll](/articles/testing-your-github-pages-site-locally-with-jekyll)."
|
||||
|
||||
When you create a pull request to update your publishing source on {% data variables.product.product_name %}, you can see build error messages on the **Checks** tab of the pull request. For more information, see "[About status checks](/articles/about-status-checks)."
|
||||
|
||||
When you push changes to your publishing source on {% data variables.product.product_name %}, {% data variables.product.prodname_pages %} will attempt to build your site. If the build fails, you'll receive an email at your primary email address. You'll also receive emails for build warnings. {% data reusables.pages.build-failure-email-server %}
|
||||
|
||||
You can see build failures (but not build warnings) for your site on {% data variables.product.product_name %} in the **Settings** tab of your site's repository.
|
||||
|
||||
You can configure a third-party service, such as [Travis CI](https://travis-ci.org/), to display error messages after each commit.
|
||||
|
||||
1. If you haven't already, add a file called _Gemfile_ in the root of your publishing source, with the following content:
|
||||
```ruby
|
||||
source `https://rubygems.org`
|
||||
gem `github-pages`
|
||||
```
|
||||
|
||||
2. Configure your site's repository for the testing service of your choice. For example, to use [Travis CI](https://travis-ci.org/), add a file named _.travis.yml_ in the root of your publishing source, with the following content:
|
||||
```yaml
|
||||
language: ruby
|
||||
rvm:
|
||||
- 2.3
|
||||
script: "bundle exec jekyll build"
|
||||
```
|
||||
3. You may need to activate your repository with the third-party testing service. For more information, see your testing service's documentation.
|
||||
@@ -1,72 +0,0 @@
|
||||
---
|
||||
title: Adding a theme to your GitHub Pages site using Jekyll
|
||||
intro: You can personalize your Jekyll site by adding and customizing a theme.
|
||||
redirect_from:
|
||||
- /articles/customizing-css-and-html-in-your-jekyll-theme/
|
||||
- /articles/adding-a-jekyll-theme-to-your-github-pages-site/
|
||||
- /articles/adding-a-theme-to-your-github-pages-site-using-jekyll
|
||||
product: '{% data reusables.gated-features.pages %}'
|
||||
versions:
|
||||
free-pro-team: '*'
|
||||
enterprise-server: '*'
|
||||
github-ae: '*'
|
||||
topics:
|
||||
- pages
|
||||
---
|
||||
|
||||
People with write permissions for a repository can add a theme to a {% data variables.product.prodname_pages %} site using Jekyll.
|
||||
|
||||
{% data reusables.pages.test-locally %}
|
||||
|
||||
### Adding a theme
|
||||
|
||||
{% data reusables.pages.navigate-site-repo %}
|
||||
{% data reusables.pages.navigate-publishing-source %}
|
||||
2. Navigate to *_config.yml*.
|
||||
{% data reusables.repositories.edit-file %}
|
||||
4. Add a new line to the file for the theme name.
|
||||
- To use a supported theme, type `theme: THEME-NAME`, replacing _THEME-NAME_ with the name of the theme as shown in the README of the theme's repository. For a list of supported themes, see "[Supported themes](https://pages.github.com/themes/)" on the {% data variables.product.prodname_pages %} site.
|
||||
|
||||
- To use any other Jekyll theme hosted on {% data variables.product.prodname_dotcom %}, type `remote_theme: THEME-NAME`, replacing THEME-NAME with the name of the theme as shown in the README of the theme's repository.
|
||||
|
||||
{% data reusables.files.write_commit_message %}
|
||||
{% data reusables.files.choose-commit-email %}
|
||||
{% data reusables.files.choose_commit_branch %}
|
||||
{% data reusables.files.propose_file_change %}
|
||||
|
||||
### Customizing your theme's CSS
|
||||
|
||||
{% data reusables.pages.best-with-supported-themes %}
|
||||
|
||||
{% data reusables.pages.theme-customization-help %}
|
||||
|
||||
{% data reusables.pages.navigate-site-repo %}
|
||||
{% data reusables.pages.navigate-publishing-source %}
|
||||
1. Create a new file called _/assets/css/style.scss_.
|
||||
2. Add the following content to the top of the file:
|
||||
```scss
|
||||
---
|
||||
---
|
||||
|
||||
@import "{{ site.theme }}";
|
||||
```
|
||||
3. Add any custom CSS or Sass (including imports) you'd like immediately after the `@import` line.
|
||||
|
||||
### Customizing your theme's HTML layout
|
||||
|
||||
{% data reusables.pages.best-with-supported-themes %}
|
||||
|
||||
{% data reusables.pages.theme-customization-help %}
|
||||
|
||||
1. On {% data variables.product.prodname_dotcom %}, navigate to your theme's source repository. For example, the source repository for Minima is https://github.com/jekyll/minima.
|
||||
2. In the *_layouts* folder, navigate to your theme's _default.html_ file.
|
||||
3. Copy the contents of the file.
|
||||
{% data reusables.pages.navigate-site-repo %}
|
||||
{% data reusables.pages.navigate-publishing-source %}
|
||||
6. Create a file called *_layouts/default.html*.
|
||||
7. Paste the default layout content you copied earlier.
|
||||
8. Customize the layout as you'd like.
|
||||
|
||||
### Further reading
|
||||
|
||||
- "[Creating new files](/articles/creating-new-files)"
|
||||
@@ -1,47 +0,0 @@
|
||||
---
|
||||
title: Adding a theme to your GitHub Pages site with the theme chooser
|
||||
intro: 'You can add a theme to your {% data variables.product.prodname_pages %} site to customize your site’s look and feel.'
|
||||
redirect_from:
|
||||
- /articles/creating-a-github-pages-site-with-the-jekyll-theme-chooser/
|
||||
- /articles/adding-a-jekyll-theme-to-your-github-pages-site-with-the-jekyll-theme-chooser/
|
||||
- /articles/adding-a-theme-to-your-github-pages-site-with-the-theme-chooser
|
||||
product: '{% data reusables.gated-features.pages %}'
|
||||
versions:
|
||||
free-pro-team: '*'
|
||||
topics:
|
||||
- pages
|
||||
---
|
||||
|
||||
People with admin permissions for a repository can use the theme chooser to add a theme to a {% data variables.product.prodname_pages %} site.
|
||||
|
||||
### About the theme chooser
|
||||
|
||||
The theme chooser adds a Jekyll theme to your repository. For more information about Jekyll, see "[About {% data variables.product.prodname_pages %} and Jekyll](/articles/about-github-pages-and-jekyll)."
|
||||
|
||||
How the theme chooser works depends on whether your repository is public or private.
|
||||
- If {% data variables.product.prodname_pages %} is already enabled for your repository, the theme chooser will add your theme to the current publishing source.
|
||||
- If your repository is public and {% data variables.product.prodname_pages %} is disabled for your repository, using the theme chooser will enable {% data variables.product.prodname_pages %} and configure the default branch as your publishing source.
|
||||
- If your repository is private and {% data variables.product.prodname_pages %} is disabled for your repository, you must enable {% data variables.product.prodname_pages %} by configuring a publishing source before you can use the theme chooser.
|
||||
|
||||
For more information about publishing sources, see "[About {% data variables.product.prodname_pages %}](/articles/about-github-pages#publishing-sources-for-github-pages-sites)."
|
||||
|
||||
If you manually added a Jekyll theme to your repository in the past, those files may be applied even after you use the theme chooser. To avoid conflicts, remove all manually added theme folders and files before using the theme chooser. For more information, see "[Adding a theme to your {% data variables.product.prodname_pages %} site using Jekyll](/articles/adding-a-theme-to-your-github-pages-site-using-jekyll)."
|
||||
|
||||
### Adding a theme with the theme chooser
|
||||
|
||||
{% data reusables.pages.navigate-site-repo %}
|
||||
{% data reusables.repositories.sidebar-settings %}
|
||||
3. Under "{% data variables.product.prodname_pages %}," click **Choose a theme** or **Change theme**.
|
||||
|
||||
4. On the top of the page, click the theme you want, then click **Select theme**.
|
||||
|
||||
5. You may be prompted to edit your site's *README.md* file.
|
||||
- To edit the file later, click **Cancel**.
|
||||
|
||||
- To edit the file now, see "[Editing files in your repository](/articles/editing-files-in-your-repository/)."
|
||||
|
||||
Your chosen theme will automatically apply to markdown files in your repository. To apply your theme to HTML files in your repository, you need to add YAML front matter that specifies a layout to each file. For more information, see "[Front Matter](https://jekyllrb.com/docs/front-matter/)" on the Jekyll site.
|
||||
|
||||
### Further reading
|
||||
|
||||
- [Themes](https://jekyllrb.com/docs/themes/) on the Jekyll site
|
||||
@@ -1,71 +0,0 @@
|
||||
---
|
||||
title: Adding content to your GitHub Pages site using Jekyll
|
||||
intro: 'You can add a new page or post to your Jekyll site on {% data variables.product.prodname_pages %}.'
|
||||
product: '{% data reusables.gated-features.pages %}'
|
||||
redirect_from:
|
||||
- /articles/adding-content-to-your-github-pages-site-using-jekyll
|
||||
versions:
|
||||
free-pro-team: '*'
|
||||
enterprise-server: '*'
|
||||
github-ae: '*'
|
||||
topics:
|
||||
- pages
|
||||
---
|
||||
|
||||
People with write permissions for a repository can add content to a {% data variables.product.prodname_pages %} site using Jekyll.
|
||||
|
||||
### About content in Jekyll sites
|
||||
|
||||
Before you can add content to a Jekyll site on {% data variables.product.prodname_pages %}, you must create a Jekyll site. For more information, see "[Creating a {% data variables.product.prodname_pages %} site with Jekyll](/articles/creating-a-github-pages-site-with-jekyll)."
|
||||
|
||||
The main types of content for Jekyll sites are pages and posts. A page is for standalone content that isn't associated with a specific date, such as an "About" page. The default Jekyll site contains a file called `about.md`, which renders as a page on your site at `YOUR-SITE-URL/about`. You can edit the contents of that file to personalize your "About" page, and you can use the "About" page as a template to create new pages. For more information, see "[Pages](https://jekyllrb.com/docs/pages/)" in the Jekyll documentation.
|
||||
|
||||
A post is a blog post. The default Jekyll site contains a directory named `_posts` that contains a default post file. You can edit the contents of that post, and you can use the default post as a template to create new posts. For more information, see "[Posts](https://jekyllrb.com/docs/posts/)" in the Jekyll documentation.
|
||||
|
||||
Your theme includes default layouts, includes, and stylesheets that will automatically be applied to new pages and posts on your site, but you can override any of these defaults. For more information, see "[About {% data variables.product.prodname_pages %} and Jekyll](/articles/about-github-pages-and-jekyll#themes)."
|
||||
|
||||
{% data reusables.pages.about-front-matter %}
|
||||
|
||||
{% data reusables.pages.test-locally %}
|
||||
|
||||
### Adding a new page to your site
|
||||
|
||||
{% data reusables.pages.navigate-site-repo %}
|
||||
{% data reusables.pages.navigate-publishing-source %}
|
||||
3. In the root of your publishing source, create a new file for your page called _PAGE-NAME.md_, replacing _PAGE-NAME_ with a meaningful filename for the page.
|
||||
4. Add the following YAML frontmatter to the top of the file, replacing _PAGE TITLE_ with the page's title and _URL-PATH_ with a path you want for the page's URL. For example, if the base URL of your site is `https://octocat.github.io` and your _URL-PATH_ is `/about/contact/`, your page will be located at `https://octocat.github.io/about/contact`.
|
||||
```shell
|
||||
layout: page
|
||||
title: "<em>PAGE TITLE</em>"
|
||||
permalink: /<em>URL-PATH</em>/
|
||||
```
|
||||
5. Below the frontmatter, add content for your page.
|
||||
{% data reusables.files.write_commit_message %}
|
||||
{% data reusables.files.choose-commit-email %}
|
||||
{% data reusables.files.choose_commit_branch %}
|
||||
{% data reusables.files.propose_file_change %}
|
||||
|
||||
### Adding a new post to your site
|
||||
|
||||
{% data reusables.pages.navigate-site-repo %}
|
||||
{% data reusables.pages.navigate-publishing-source %}
|
||||
3. Navigate to the `_posts` directory.
|
||||
4. Create a new file called _YYYY-MM-DD-NAME-OF-POST.md_, replacing _YYYY-MM-DD_ with the date of your post and _NAME-OF-POST_ with the name of your post.
|
||||
4. Add the following YAML frontmatter to the top of the file, replacing _POST TITLE_ with the post's title, _YYYY-MM-DD hh:mm:ss -0000_ with the date and time for the post, and _CATEGORY-1_ and _CATEGORY-2_ with as many categories you want for your post.
|
||||
```shell
|
||||
layout: post
|
||||
title: "<em>POST TITLE</em>"
|
||||
date: </em>YYYY-MM-DD hh:mm:ss -0000</em>
|
||||
categories: <em>CATEGORY-1</em> <em>CATEGORY-2</em>
|
||||
```
|
||||
5. Below the frontmatter, add content for your post.
|
||||
{% data reusables.files.write_commit_message %}
|
||||
{% data reusables.files.choose-commit-email %}
|
||||
{% data reusables.files.choose_commit_branch %}
|
||||
{% data reusables.files.propose_file_change %}
|
||||
|
||||
Your post should now be up on your site! If the base URL of your site is `https://octocat.github.io`, then your new post will be located at `https://octocat.github.io/YYYY/MM/DD/TITLE.html`.
|
||||
|
||||
### Next steps
|
||||
|
||||
{% data reusables.pages.add-jekyll-theme %} For more information, see "[Adding a theme to your {% data variables.product.prodname_pages %} site using Jekyll](/articles/adding-a-theme-to-your-github-pages-site-using-jekyll)."
|
||||
@@ -1,36 +0,0 @@
|
||||
---
|
||||
title: Changing the visibility of your GitHub Pages site
|
||||
intro: 'You can manage access control for your project site by publishing the site publicly or privately.'
|
||||
product: '{% data reusables.gated-features.private-pages %}'
|
||||
versions:
|
||||
free-pro-team: '*'
|
||||
permissions: People with admin permissions for a repository can change the visibility of a {% data variables.product.prodname_pages %} site.
|
||||
---
|
||||
|
||||
### About access control for {% data variables.product.prodname_pages %} sites
|
||||
|
||||
If your project site is published from a private or internal repository that's owned by an organization using {% data variables.product.prodname_ghe_cloud %}, you can manage access control for the site. With access control, you can choose to publish the site publicly to anyone on the internet or privately to people with read access to your repository. A privately published site can be used to share your internal documentation or knowledge base with members of your enterprise. You cannot manage access control for an organization site. For more information about the types of {% data variables.product.prodname_pages %} sites, see "[About GitHub Pages](/github/working-with-github-pages/about-github-pages#types-of-github-pages-sites)."
|
||||
|
||||
Privately published sites are available at a different subdomain than publicly published sites. This ensures that your {% data variables.product.prodname_pages %} site is secure from the moment it's published:
|
||||
|
||||
- We automatically secure every subdomain of `*.pages.github.io` with a TLS certificate, and enforce HSTS to ensure that browsers always serve the page over HTTPS.
|
||||
- We use a unique subdomain for the private page to ensure that other repositories in your organization cannot publish content on the same origin as the private page. This protects your private page from "[cookie tossing](https://github.blog/2013-04-09-yummy-cookies-across-domains/)". This is also why we don't host {% data variables.product.prodname_pages %} sites on the `github.com` domain.
|
||||
|
||||
You can see your site's unique subdomain in the pages tab of your repository settings. If you're using a static site generator configured to build the site with the repository name as a path, you may need to update the settings for the static site generator when changing the site to private. For more information, see "[Configuring Jekyll in your {% data variables.product.prodname_pages %} site](/github/working-with-github-pages/managing-a-custom-domain-for-your-github-pages-site#configuring-a-subdomain)" or the documentation for your static site generator.
|
||||
|
||||
To use a shorter and more memorable domain for your private {% data variables.product.prodname_pages %} site, you can configure a custom domain. For more information, see "[Configuring a custom domain for your {% data variables.product.prodname_pages %} site](/github/working-with-github-pages/configuring-a-custom-domain-for-your-github-pages-site)."
|
||||
|
||||
### Changing the visibility of your {% data variables.product.prodname_pages %} site
|
||||
|
||||
{% data reusables.pages.navigate-site-repo %}
|
||||
{% data reusables.repositories.sidebar-settings %}
|
||||
3. Under "{% data variables.product.prodname_pages %}", select the **{% data variables.product.prodname_pages %} visibility** drop-down menu, then click a visibility.
|
||||
|
||||
4. To see your published site, under "{% data variables.product.prodname_pages %}", click your site's URL.
|
||||
|
||||
|
||||
{% note %}
|
||||
|
||||
{% data reusables.pages.twenty-minutes-to-publish %}
|
||||
|
||||
{% endnote %}
|
||||
@@ -1,20 +0,0 @@
|
||||
---
|
||||
title: Configuring a custom domain for your GitHub Pages site
|
||||
intro: 'You can customize the domain name of your {% data variables.product.prodname_pages %} site.'
|
||||
redirect_from:
|
||||
- /articles/tips-for-configuring-an-a-record-with-your-dns-provider/
|
||||
- /articles/adding-or-removing-a-custom-domain-for-your-github-pages-site/
|
||||
- /articles/configuring-an-a-record-with-your-dns-provider/
|
||||
- /articles/using-a-custom-domain-with-github-pages/
|
||||
- /articles/tips-for-configuring-a-cname-record/
|
||||
- /articles/setting-up-a-custom-domain-with-pages/
|
||||
- /articles/setting-up-a-custom-domain-with-github-pages/
|
||||
- /articles/configuring-a-custom-domain-for-your-github-pages-site
|
||||
product: '{% data reusables.gated-features.pages %}'
|
||||
mapTopic: true
|
||||
versions:
|
||||
free-pro-team: '*'
|
||||
topics:
|
||||
- pages
|
||||
---
|
||||
|
||||
@@ -1,41 +0,0 @@
|
||||
---
|
||||
title: Configuring a publishing source for your GitHub Pages site
|
||||
intro: 'If you use the default publishing source for your {% data variables.product.prodname_pages %} site, your site will publish automatically. You can also choose to publish your{% if currentVersion ver_lt "enterprise-server@2.23" %} project{% endif %} site from a different branch or folder.'
|
||||
redirect_from:
|
||||
- /articles/configuring-a-publishing-source-for-github-pages/
|
||||
- /articles/configuring-a-publishing-source-for-your-github-pages-site
|
||||
product: '{% data reusables.gated-features.pages %}'
|
||||
permissions: 'People with admin or maintainer permissions for a repository can configure a publishing source for a {% data variables.product.prodname_pages %} site.'
|
||||
versions:
|
||||
free-pro-team: '*'
|
||||
enterprise-server: '*'
|
||||
github-ae: '*'
|
||||
topics:
|
||||
- pages
|
||||
---
|
||||
|
||||
For more information about publishing sources, see "[About {% data variables.product.prodname_pages %}](/articles/about-github-pages#publishing-sources-for-github-pages-sites)."
|
||||
|
||||
### Choosing a publishing source
|
||||
|
||||
Before you configure a publishing source, make sure the branch{% if currentVersion ver_lt "enterprise-server@2.23" %} or folder{% endif %} you want to use as your publishing source already exists in your repository.{% if currentVersion ver_lt "enterprise-server@2.23" %} For example, before you can publish your project site from the `/docs` folder on the `master` branch of your repository, you or a collaborator must create a `/docs` folder on the default `master` branch of your repository.{% endif %}
|
||||
|
||||
{% data reusables.pages.navigate-site-repo %}
|
||||
{% data reusables.repositories.sidebar-settings %}
|
||||
{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.22" or currentVersion == "github-ae@latest" %}
|
||||
3. Under "{% data variables.product.prodname_pages %}", use the **None** or **Branch** drop-down menu and select a publishing source.
|
||||
|
||||
4. Optionally, use the drop-down menu to select a folder for your publishing source.
|
||||
|
||||
5. Click **Save**.
|
||||
|
||||
{% else %}
|
||||
3. Under "{% data variables.product.prodname_pages %}", use the **Source** drop-down menu and select a publishing source.
|
||||
|
||||
{% endif %}
|
||||
|
||||
### Troubleshooting publishing problems with your {% data variables.product.prodname_pages %} site
|
||||
|
||||
{% data reusables.pages.admin-must-push %}
|
||||
|
||||
If you choose the `docs` folder on {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.22" or currentVersion == "github-ae@latest" %}any{% else %}the `master`{% endif %} branch as your publishing source, then later remove the `/docs` folder from that branch in your repository, your site won't build and you'll get a page build error message for a missing `/docs` folder. For more information, see "[Troubleshooting Jekyll build errors for {% data variables.product.prodname_pages %} sites](/articles/troubleshooting-jekyll-build-errors-for-github-pages-sites#missing-docs-folder)."
|
||||
@@ -1,35 +0,0 @@
|
||||
---
|
||||
title: Creating a custom 404 page for your GitHub Pages site
|
||||
intro: You can display a custom 404 error page when people try to access nonexistent pages on your site.
|
||||
redirect_from:
|
||||
- /articles/custom-404-pages/
|
||||
- /articles/creating-a-custom-404-page-for-your-github-pages-site
|
||||
product: '{% data reusables.gated-features.pages %}'
|
||||
versions:
|
||||
free-pro-team: '*'
|
||||
enterprise-server: '*'
|
||||
github-ae: '*'
|
||||
topics:
|
||||
- pages
|
||||
---
|
||||
|
||||
{% data reusables.pages.navigate-site-repo %}
|
||||
{% data reusables.pages.navigate-publishing-source %}
|
||||
{% data reusables.files.add-file %}
|
||||
3. In the file name field, type `404.html` or `404.md`.
|
||||
|
||||
4. If you named your file `404.md`, add the following YAML front matter to the beginning of the file:
|
||||
```yaml
|
||||
---
|
||||
permalink: /404.html
|
||||
---
|
||||
```
|
||||
5. Below the YAML front matter, if present, add the content you want to display on your 404 page.
|
||||
{% data reusables.files.write_commit_message %}
|
||||
{% data reusables.files.choose-commit-email %}
|
||||
{% data reusables.files.choose_commit_branch %}
|
||||
{% data reusables.files.propose_new_file %}
|
||||
|
||||
### Further reading
|
||||
|
||||
- [Front matter](http://jekyllrb.com/docs/frontmatter) in the Jekyll documentation
|
||||
@@ -1,113 +0,0 @@
|
||||
---
|
||||
title: Creating a GitHub Pages site with Jekyll
|
||||
intro: 'You can use Jekyll to create a {% data variables.product.prodname_pages %} site in a new or existing repository.'
|
||||
product: '{% data reusables.gated-features.pages %}'
|
||||
redirect_from:
|
||||
- /articles/creating-a-github-pages-site-with-jekyll
|
||||
permissions: 'People with admin permissions for a repository can create a {% data variables.product.prodname_pages %} site with Jekyll.'
|
||||
versions:
|
||||
free-pro-team: '*'
|
||||
enterprise-server: '*'
|
||||
github-ae: '*'
|
||||
topics:
|
||||
- pages
|
||||
---
|
||||
|
||||
{% data reusables.pages.org-owners-can-restrict-pages-creation %}
|
||||
|
||||
### Prerequisites
|
||||
|
||||
Before you can use Jekyll to create a {% data variables.product.prodname_pages %} site, you must install Jekyll and Git. For more information, see [Installation](https://jekyllrb.com/docs/installation/) in the Jekyll documentation and "[Set up Git](/articles/set-up-git)."
|
||||
|
||||
{% data reusables.pages.recommend-bundler %}
|
||||
|
||||
{% data reusables.pages.jekyll-install-troubleshooting %}
|
||||
|
||||
### Creating a repository for your site
|
||||
|
||||
{% data reusables.pages.new-or-existing-repo %}
|
||||
|
||||
{% data reusables.repositories.create_new %}
|
||||
{% data reusables.repositories.owner-drop-down %}
|
||||
{% data reusables.pages.create-repo-name %}
|
||||
{% data reusables.repositories.choose-repo-visibility %}
|
||||
|
||||
### Creating your site
|
||||
|
||||
{% data reusables.pages.must-have-repo-first %}
|
||||
|
||||
{% data reusables.pages.private_pages_are_public_warning %}
|
||||
|
||||
{% data reusables.command_line.open_the_multi_os_terminal %}
|
||||
2. If you don't already have a local copy of your repository, navigate to the location where you want to store your site's source files, replacing _PARENT-FOLDER_ with the folder you want to contain the folder for your repository.
|
||||
```shell
|
||||
$ cd <em>PARENT-FOLDER</em>
|
||||
```
|
||||
3. If you haven't already, initialize a local Git repository, replacing _REPOSITORY-NAME_ with the name of your repository.
|
||||
```shell
|
||||
$ git init <em>REPOSITORY-NAME</em>
|
||||
> Initialized empty Git repository in /Users/octocat/my-site/.git/
|
||||
# Creates a new folder on your computer, initialized as a Git repository
|
||||
```
|
||||
4. Change directories to the repository.
|
||||
```shell
|
||||
$ cd <em>REPOSITORY-NAME</em>
|
||||
# Changes the working directory
|
||||
```
|
||||
{% data reusables.pages.decide-publishing-source %}
|
||||
{% data reusables.pages.navigate-publishing-source %}
|
||||
For example, if you chose to publish your site from the `docs` folder on the default branch, create and change directories to the `docs` folder.
|
||||
```shell
|
||||
$ mkdir docs
|
||||
# Creates a new folder called docs
|
||||
$ cd docs
|
||||
```
|
||||
If you chose to publish your site from the `gh-pages` branch, create and checkout the `gh-pages` branch.
|
||||
```shell
|
||||
$ git checkout --orphan gh-pages
|
||||
# Creates a new branch, with no history or contents, called gh-pages and switches to the gh-pages branch
|
||||
```
|
||||
7. To create a new Jekyll site, use the `jekyll new` command:
|
||||
```shell
|
||||
$ jekyll new .
|
||||
# Creates a Jekyll site in the current directory
|
||||
```
|
||||
8. Open the Gemfile that Jekyll created.
|
||||
1. Add "#" to the beginning of the line that starts with `gem "jekyll"` to comment out this line.
|
||||
1. Add the `github-pages` gem by editing the line starting with `# gem "github-pages"`. Change this line to:
|
||||
|
||||
```shell
|
||||
gem "github-pages", "~> GITHUB-PAGES-VERSION", group: :jekyll_plugins
|
||||
```
|
||||
|
||||
Replace _GITHUB-PAGES-VERSION_ with the latest supported version of the `github-pages` gem. You can find this version here: "[Dependency versions](https://pages.github.com/versions/)."
|
||||
|
||||
The correct version Jekyll will be installed as a dependency of the `github-pages` gem.
|
||||
10. Save and close the Gemfile.
|
||||
11. From the command line, run `bundle update`.
|
||||
11. Optionally, test your site locally. For more information, see "[Testing your {% data variables.product.prodname_pages %} site locally with Jekyll](/articles/testing-your-github-pages-site-locally-with-jekyll)."
|
||||
12. Add your {% data variables.product.product_name %} repository as a remote, replacing {% if enterpriseServerVersions contains currentVersion or currentVersion == "github-ae@latest" %}_HOSTNAME_ with your enterprise's hostname,{% endif %} _USER_ with the account that owns the repository{% if enterpriseServerVersions contains currentVersion or currentVersion == "github-ae@latest" %},{% endif %} and _REPOSITORY_ with the name of the repository.
|
||||
```shell
|
||||
{% if currentVersion == "free-pro-team@latest" %}
|
||||
$ git remote add origin https://github.com/<em>USER</em>/<em>REPOSITORY</em>.git
|
||||
{% else %}
|
||||
$ git remote add origin https://<em>HOSTNAME</em>/<em>USER</em>/<em>REPOSITORY</em>.git
|
||||
{% endif %}
|
||||
```
|
||||
13. Push the repository to {% data variables.product.product_name %}, replacing _BRANCH_ with the name of the branch you're working on.
|
||||
```shell
|
||||
$ git push -u origin <em>BRANCH</em>
|
||||
```
|
||||
{% data reusables.pages.configure-publishing-source %}
|
||||
{% data reusables.pages.navigate-site-repo %}
|
||||
{% data reusables.repositories.sidebar-settings %}{% if currentVersion == "free-pro-team@latest" %}
|
||||
{% data reusables.pages.choose-visibility %}{% endif %}
|
||||
{% data reusables.pages.visit-site %}
|
||||
|
||||
{% data reusables.pages.admin-must-push %}
|
||||
|
||||
### Next steps
|
||||
|
||||
To add a new page or post to your site, see "[Adding content to your {% data variables.product.prodname_pages %} site using Jekyll](/articles/adding-content-to-your-github-pages-site-using-jekyll)."
|
||||
|
||||
{% data reusables.pages.add-jekyll-theme %} For more information, see "[Adding a theme to your {% data variables.product.prodname_pages %} site using Jekyll](/articles/adding-a-theme-to-your-github-pages-site-using-jekyll)."
|
||||
@@ -1,61 +0,0 @@
|
||||
---
|
||||
title: Creating a GitHub Pages site
|
||||
intro: 'You can create a {% data variables.product.prodname_pages %} site in a new or existing repository.'
|
||||
redirect_from:
|
||||
- /articles/creating-pages-manually/
|
||||
- /articles/creating-project-pages-manually/
|
||||
- /articles/creating-project-pages-from-the-command-line/
|
||||
- /articles/creating-project-pages-using-the-command-line/
|
||||
- /articles/creating-a-github-pages-site
|
||||
product: '{% data reusables.gated-features.pages %}'
|
||||
versions:
|
||||
free-pro-team: '*'
|
||||
enterprise-server: '*'
|
||||
github-ae: '*'
|
||||
topics:
|
||||
- pages
|
||||
---
|
||||
|
||||
{% data reusables.pages.org-owners-can-restrict-pages-creation %}
|
||||
|
||||
### Creating a repository for your site
|
||||
|
||||
{% data reusables.pages.new-or-existing-repo %}
|
||||
|
||||
{% data reusables.repositories.create_new %}
|
||||
{% data reusables.repositories.owner-drop-down %}
|
||||
{% data reusables.pages.create-repo-name %}
|
||||
{% data reusables.repositories.choose-repo-visibility %}
|
||||
{% data reusables.repositories.initialize-with-readme %}
|
||||
{% data reusables.repositories.create-repo %}
|
||||
|
||||
### Creating your site
|
||||
|
||||
{% data reusables.pages.must-have-repo-first %}
|
||||
|
||||
{% data reusables.pages.private_pages_are_public_warning %}
|
||||
|
||||
{% data reusables.pages.navigate-site-repo %}
|
||||
{% data reusables.pages.decide-publishing-source %}
|
||||
3. If your chosen publishing source already exists, navigate to the publishing source. If your chosen publishing source doesn't exist, create the publishing source.
|
||||
4. In the root of the publishing source, create a new file called `index.md` that contains the content you want to display on the main page of your site.
|
||||
{% data reusables.pages.configure-publishing-source %}
|
||||
{% data reusables.repositories.sidebar-settings %}{% if currentVersion == "free-pro-team@latest" %}
|
||||
{% data reusables.pages.choose-visibility %}{% endif %}
|
||||
{% data reusables.pages.visit-site %}
|
||||
|
||||
{% data reusables.pages.admin-must-push %}
|
||||
|
||||
### Next steps
|
||||
|
||||
You can add more pages to your site by creating more new files. Each file will be available on your site in the same directory structure as your publishing source. For example, if the publishing source for your project site is the `gh-pages` branch, and you create a new file called `/about/contact-us.md` on the `gh-pages` branch, the file will be available at {% if currentVersion == "free-pro-team@latest" %}`https://<user>.github.io/<repository>/{% else %}`http(s)://<hostname>/pages/<username>/<repository>/{% endif %}about/contact-us.html`.
|
||||
|
||||
You can also add a theme to customize your site’s look and feel. For more information, see {% if currentVersion == "free-pro-team@latest" %}"[Adding a theme to your {% data variables.product.prodname_pages %} site with the theme chooser](/articles/adding-a-theme-to-your-github-pages-site-with-the-theme-chooser){% else %}"[Adding a theme to your {% data variables.product.prodname_pages %} site using Jekyll](/articles/adding-a-theme-to-your-github-pages-site-using-jekyll){% endif %}."
|
||||
|
||||
To customize your site even more, you can use Jekyll, a static site generator with built-in support for {% data variables.product.prodname_pages %}. For more information, see "[About {% data variables.product.prodname_pages %} and Jekyll](/articles/about-github-pages-and-jekyll)."
|
||||
|
||||
### Further reading
|
||||
|
||||
- "[Troubleshooting Jekyll build errors for {% data variables.product.prodname_pages %} sites](/articles/troubleshooting-jekyll-build-errors-for-github-pages-sites)"
|
||||
- "[Creating and deleting branches within your repository](/articles/creating-and-deleting-branches-within-your-repository)"
|
||||
- "[Creating new files](/articles/creating-new-files)"
|
||||
@@ -1,17 +0,0 @@
|
||||
---
|
||||
title: Getting started with GitHub Pages
|
||||
intro: 'You can set up a basic {% data variables.product.prodname_pages %} site for yourself, your organization, or your project.'
|
||||
redirect_from:
|
||||
- /categories/github-pages-basics
|
||||
- /articles/additional-customizations-for-github-pages/
|
||||
- /articles/getting-started-with-github-pages
|
||||
product: '{% data reusables.gated-features.pages %}'
|
||||
mapTopic: true
|
||||
versions:
|
||||
free-pro-team: '*'
|
||||
enterprise-server: '*'
|
||||
github-ae: '*'
|
||||
topics:
|
||||
- pages
|
||||
---
|
||||
|
||||
@@ -1,47 +0,0 @@
|
||||
---
|
||||
title: Working with GitHub Pages
|
||||
shortTitle: GitHub Pages
|
||||
intro: 'You can create a website directly from a {% data variables.product.product_name %} repository.'
|
||||
redirect_from:
|
||||
- /categories/20/articles/
|
||||
- /categories/95/articles/
|
||||
- /categories/github-pages-features/
|
||||
- /pages/
|
||||
- /categories/96/articles/
|
||||
- /categories/github-pages-troubleshooting/
|
||||
- /categories/working-with-github-pages
|
||||
product: '{% data reusables.gated-features.pages %}'
|
||||
versions:
|
||||
free-pro-team: '*'
|
||||
enterprise-server: '*'
|
||||
github-ae: '*'
|
||||
topics:
|
||||
- pages
|
||||
---
|
||||
|
||||
|
||||
### Table of Contents
|
||||
|
||||
{% topic_link_in_list /getting-started-with-github-pages %}
|
||||
{% link_in_list /about-github-pages %}
|
||||
{% link_in_list /creating-a-github-pages-site %}
|
||||
{% link_in_list /adding-a-theme-to-your-github-pages-site-with-the-theme-chooser %}
|
||||
{% link_in_list /configuring-a-publishing-source-for-your-github-pages-site %}
|
||||
{% link_in_list /changing-the-visibility-of-your-github-pages-site %}
|
||||
{% link_in_list /creating-a-custom-404-page-for-your-github-pages-site %}
|
||||
{% link_in_list /securing-your-github-pages-site-with-https %}
|
||||
{% link_in_list /using-submodules-with-github-pages %}
|
||||
{% link_in_list /unpublishing-a-github-pages-site %}
|
||||
{% topic_link_in_list /setting-up-a-github-pages-site-with-jekyll %}
|
||||
{% link_in_list /about-github-pages-and-jekyll %}
|
||||
{% link_in_list /creating-a-github-pages-site-with-jekyll %}
|
||||
{% link_in_list /testing-your-github-pages-site-locally-with-jekyll %}
|
||||
{% link_in_list /adding-content-to-your-github-pages-site-using-jekyll %}
|
||||
{% link_in_list /setting-a-markdown-processor-for-your-github-pages-site-using-jekyll %}
|
||||
{% link_in_list /adding-a-theme-to-your-github-pages-site-using-jekyll %}
|
||||
{% link_in_list /about-jekyll-build-errors-for-github-pages-sites %}
|
||||
{% link_in_list /troubleshooting-jekyll-build-errors-for-github-pages-sites %}
|
||||
{% topic_link_in_list /configuring-a-custom-domain-for-your-github-pages-site %}
|
||||
{% link_in_list /about-custom-domains-and-github-pages %}
|
||||
{% link_in_list /managing-a-custom-domain-for-your-github-pages-site %}
|
||||
{% link_in_list /troubleshooting-custom-domains-and-github-pages %}
|
||||
@@ -1,96 +0,0 @@
|
||||
---
|
||||
title: Managing a custom domain for your GitHub Pages site
|
||||
intro: 'You can set up or update certain DNS records and your repository settings to point the default domain for your {% data variables.product.prodname_pages %} site to a custom domain.'
|
||||
redirect_from:
|
||||
- /articles/quick-start-setting-up-a-custom-domain/
|
||||
- /articles/setting-up-an-apex-domain/
|
||||
- /articles/setting-up-a-www-subdomain/
|
||||
- /articles/setting-up-a-custom-domain/
|
||||
- /articles/setting-up-an-apex-domain-and-www-subdomain/
|
||||
- /articles/adding-a-cname-file-to-your-repository/
|
||||
- /articles/setting-up-your-pages-site-repository/
|
||||
- /articles/managing-a-custom-domain-for-your-github-pages-site
|
||||
product: '{% data reusables.gated-features.pages %}'
|
||||
versions:
|
||||
free-pro-team: '*'
|
||||
topics:
|
||||
- pages
|
||||
---
|
||||
|
||||
People with admin permissions for a repository can configure a custom domain for a {% data variables.product.prodname_pages %} site.
|
||||
|
||||
### About custom domain configuration
|
||||
|
||||
Make sure you add your custom domain to your {% data variables.product.prodname_pages %} site before configuring your custom domain with your DNS provider. Configuring your custom domain with your DNS provider without adding your custom domain to {% data variables.product.product_name %} could result in someone else being able to host a site on one of your subdomains.
|
||||
|
||||
{% windows %}
|
||||
|
||||
The `dig` command, which can be used to verify correct configuration of DNS records, is not included in Windows. Before you can verify that your DNS records are configured correctly, you must install [BIND](https://www.isc.org/bind/).
|
||||
|
||||
{% endwindows %}
|
||||
|
||||
{% note %}
|
||||
|
||||
**Note:** DNS changes can take up to 24 hours to propagate.
|
||||
|
||||
{% endnote %}
|
||||
|
||||
### Configuring a subdomain
|
||||
|
||||
To set up a `www` or custom subdomain, such as `www.example.com` or `blog.example.com`, you must add your domain in the repository settings, which will create a CNAME file in your site’s repository. After that, configure a CNAME record with your DNS provider.
|
||||
|
||||
{% data reusables.pages.navigate-site-repo %}
|
||||
{% data reusables.repositories.sidebar-settings %}
|
||||
4. Under "Custom domain", type your custom domain, then click **Save**. This will create a commit that adds a _CNAME_ file in the root of your publishing source.
|
||||
|
||||
5. Navigate to your DNS provider and create a `CNAME` record that points your subdomain to the default domain for your site. For example, if you want to use the subdomain `www.example.com` for your user site, create a `CNAME` record that points `www.example.com` to `<user>.github.io`. If you want to use the subdomain `www.anotherexample.com` for your organization site, create a `CNAME` record that points `www.anotherexample.com` to `<organization>.github.io`. The `CNAME` record should always point to `<user>.github.io` or `<organization>.github.io`, excluding the repository name. {% data reusables.pages.contact-dns-provider %} {% data reusables.pages.default-domain-information %}
|
||||
|
||||
{% indented_data_reference site.data.reusables.pages.wildcard-dns-warning spaces=3 %}
|
||||
{% data reusables.command_line.open_the_multi_os_terminal %}
|
||||
6. To confirm that your DNS record configured correctly, use the `dig` command, replacing _WWW.EXAMPLE.COM_ with your subdomain.
|
||||
```shell
|
||||
$ dig <em>WWW.EXAMPLE.COM</em> +nostats +nocomments +nocmd
|
||||
> ;<em>WWW.EXAMPLE.COM.</em> IN A
|
||||
> <em>WWW.EXAMPLE.COM.</em> 3592 IN CNAME <em>YOUR-USERNAME</em>.github.io.
|
||||
> <em>YOUR-USERNAME</em>.github.io. 43192 IN CNAME <em> GITHUB-PAGES-SERVER </em>.
|
||||
> <em> GITHUB-PAGES-SERVER </em>. 22 IN A 192.0.2.1
|
||||
```
|
||||
{% data reusables.pages.build-locally-download-cname %}
|
||||
{% data reusables.pages.enforce-https-custom-domain %}
|
||||
|
||||
### Configuring an apex domain
|
||||
|
||||
To set up an apex domain, such as `example.com`, you must configure a _CNAME_ file in your {% data variables.product.prodname_pages %} repository and at least one `ALIAS`, `ANAME`, or `A` record with your DNS provider.
|
||||
|
||||
{% data reusables.pages.www-and-apex-domain-recommendation %} For more information, see "[Configuring a subdomain](#configuring-a-subdomain)."
|
||||
|
||||
{% data reusables.pages.navigate-site-repo %}
|
||||
{% data reusables.repositories.sidebar-settings %}
|
||||
4. Under "Custom domain", type your custom domain, then click **Save**. This will create a commit that adds a _CNAME_ file in the root of your publishing source.
|
||||
|
||||
5. Navigate to your DNS provider and create either an `ALIAS`, `ANAME`, or `A` record. {% data reusables.pages.contact-dns-provider %}
|
||||
- To create an `ALIAS` or `ANAME` record, point your apex domain to the default domain for your site. {% data reusables.pages.default-domain-information %}
|
||||
- To create `A` records, point your apex domain to the IP addresses for {% data variables.product.prodname_pages %}.
|
||||
```shell
|
||||
185.199.108.153
|
||||
185.199.109.153
|
||||
185.199.110.153
|
||||
185.199.111.153
|
||||
```
|
||||
|
||||
{% indented_data_reference site.data.reusables.pages.wildcard-dns-warning spaces=3 %}
|
||||
{% data reusables.command_line.open_the_multi_os_terminal %}
|
||||
6. To confirm that your DNS record configured correctly, use the `dig` command, replacing _EXAMPLE.COM_ with your apex domain. Confirm that the results match the IP addresses for {% data variables.product.prodname_pages %} above.
|
||||
```shell
|
||||
$ dig <em>EXAMPLE.COM</em> +noall +answer
|
||||
> <em>EXAMPLE.COM</em> 3600 IN A 185.199.108.153
|
||||
> <em>EXAMPLE.COM</em> 3600 IN A 185.199.109.153
|
||||
> <em>EXAMPLE.COM</em> 3600 IN A 185.199.110.153
|
||||
> <em>EXAMPLE.COM</em> 3600 IN A 185.199.111.153
|
||||
```
|
||||
{% data reusables.pages.build-locally-download-cname %}
|
||||
{% data reusables.pages.enforce-https-custom-domain %}
|
||||
|
||||
### Further reading
|
||||
|
||||
- "[Troubleshooting custom domains and {% data variables.product.prodname_pages %}](/articles/troubleshooting-custom-domains-and-github-pages)"
|
||||
@@ -1,56 +0,0 @@
|
||||
---
|
||||
title: Securing your GitHub Pages site with HTTPS
|
||||
intro: 'HTTPS adds a layer of encryption that prevents others from snooping on or tampering with traffic to your site. You can enforce HTTPS for your {% data variables.product.prodname_pages %} site to transparently redirect all HTTP requests to HTTPS.'
|
||||
product: '{% data reusables.gated-features.pages %}'
|
||||
redirect_from:
|
||||
- /articles/securing-your-github-pages-site-with-https
|
||||
versions:
|
||||
free-pro-team: '*'
|
||||
topics:
|
||||
- pages
|
||||
---
|
||||
|
||||
People with admin permissions for a repository can enforce HTTPS for a {% data variables.product.prodname_pages %} site.
|
||||
|
||||
### About HTTPS and {% data variables.product.prodname_pages %}
|
||||
|
||||
All {% data variables.product.prodname_pages %} sites, including sites that are correctly configured with a custom domain, support HTTPS and HTTPS enforcement. For more information about custom domains, see "[About custom domains and {% data variables.product.prodname_pages %}](/articles/about-custom-domains-and-github-pages)" and "[Troubleshooting custom domains and {% data variables.product.prodname_pages %}](/articles/troubleshooting-custom-domains-and-github-pages#https-errors)."
|
||||
|
||||
HTTPS enforcement is required for {% data variables.product.prodname_pages %} sites using a `github.io` domain that were created after June 15, 2016. If you created your site before June 15, 2016, you can manually enable HTTPS enforcement.
|
||||
|
||||
{% data reusables.pages.no_sensitive_data_pages %}
|
||||
|
||||
{% data reusables.pages.private_pages_are_public_warning %}
|
||||
|
||||
### Enforcing HTTPS for your {% data variables.product.prodname_pages %} site
|
||||
|
||||
{% data reusables.pages.navigate-site-repo %}
|
||||
{% data reusables.repositories.sidebar-settings %}
|
||||
3. Under "{% data variables.product.prodname_pages %}," select **Enforce HTTPS**.
|
||||
|
||||
|
||||
### Resolving problems with mixed content
|
||||
|
||||
If you enable HTTPS for your {% data variables.product.prodname_pages %} site but your site's HTML still references images, CSS, or JavaScript over HTTP, then your site is serving *mixed content*. Serving mixed content may make your site less secure and cause trouble loading assets.
|
||||
|
||||
To remove your site's mixed content, make sure all your assets are served over HTTPS by changing `http://` to `https://` in your site's HTML.
|
||||
|
||||
Assets are commonly found in the following locations:
|
||||
- If your site uses Jekyll, your HTML files will probably be found in the *_layouts* folder.
|
||||
- CSS is usually found in the `<head>` section of your HTML file.
|
||||
- JavaScript is usually found in the `<head>` section or just before the closing `</body>` tag.
|
||||
- Images are often found in the `<body>` section.
|
||||
|
||||
{% tip %}
|
||||
|
||||
**Tip:** If you can't find your assets in your site's source files, try searching your site's source files for `http` in your text editor or on {% data variables.product.product_name %}.
|
||||
|
||||
{% endtip %}
|
||||
|
||||
#### Examples of assets referenced in an HTML file
|
||||
|
||||
| Asset type | HTTP | HTTPS |
|
||||
|:----------:|:-----------------------------------------:|:---------------------------------:|
|
||||
| CSS | `<link rel="stylesheet" href="http://example.com/css/main.css">` | `<link rel="stylesheet" href="https://example.com/css/main.css">`
|
||||
| JavaScript | `<script type="text/javascript" src="http://example.com/js/main.js"></script>` | `<script type="text/javascript" src="https://example.com/js/main.js"></script>`
|
||||
| Image | `<A HREF="http://www.somesite.com"><IMG SRC="http://www.example.com/logo.jpg" alt="Logo"></a>` | `<A HREF="https://www.somesite.com"><IMG SRC="https://www.example.com/logo.jpg" alt="Logo"></a>`
|
||||
@@ -1,36 +0,0 @@
|
||||
---
|
||||
title: Setting a Markdown processor for your GitHub Pages site using Jekyll
|
||||
intro: 'You can choose a Markdown processor to determine how Markdown is rendered on your {% data variables.product.prodname_pages %} site.'
|
||||
redirect_from:
|
||||
- /articles/migrating-your-pages-site-from-maruku/
|
||||
- /articles/updating-your-markdown-processor-to-kramdown/
|
||||
- /articles/setting-a-markdown-processor-for-your-github-pages-site-using-jekyll
|
||||
product: '{% data reusables.gated-features.pages %}'
|
||||
versions:
|
||||
free-pro-team: '*'
|
||||
enterprise-server: '*'
|
||||
github-ae: '*'
|
||||
topics:
|
||||
- pages
|
||||
---
|
||||
|
||||
People with write permissions for a repository can set the Markdown processor for a {% data variables.product.prodname_pages %} site.
|
||||
|
||||
{% data variables.product.prodname_pages %} supports two Markdown processors: [kramdown](http://kramdown.gettalong.org/) and {% data variables.product.prodname_dotcom %}'s own extended [CommonMark](https://commonmark.org/) processor, which is used to render {% data variables.product.prodname_dotcom %} Flavored Markdown throughout {% data variables.product.product_name %}. For more information, see "[About writing and formatting on {% data variables.product.prodname_dotcom %}](/articles/about-writing-and-formatting-on-github)."
|
||||
|
||||
You can use {% data variables.product.prodname_dotcom %} Flavored Markdown with either processor, but only our CommonMark processor will always match the results you see on {% data variables.product.product_name %}.
|
||||
|
||||
{% data reusables.pages.navigate-site-repo %}
|
||||
2. In your repository, browse to the *_config.yml* file.
|
||||
{% data reusables.repositories.edit-file %}
|
||||
4. Find the line that starts with `markdown:` and change the value to `kramdown` or `GFM`.
|
||||
|
||||
{% data reusables.files.write_commit_message %}
|
||||
{% data reusables.files.choose-commit-email %}
|
||||
{% data reusables.files.choose_commit_branch %}
|
||||
{% data reusables.files.propose_new_file %}
|
||||
|
||||
### Further reading
|
||||
|
||||
- [kramdown Documentation](https://kramdown.gettalong.org/documentation.html)
|
||||
- [{% data variables.product.prodname_dotcom %} Flavored Markdown Spec](https://github.github.com/gfm/)
|
||||
@@ -1,17 +0,0 @@
|
||||
---
|
||||
title: Setting up a GitHub Pages site with Jekyll
|
||||
intro: 'You can use Jekyll, a popular static site generator, to further customize your {% data variables.product.prodname_pages %} site.'
|
||||
redirect_from:
|
||||
- /articles/using-jekyll-with-pages/
|
||||
- /articles/using-jekyll-as-a-static-site-generator-with-github-pages
|
||||
- /articles/setting-up-a-github-pages-site-with-jekyll
|
||||
product: '{% data reusables.gated-features.pages %}'
|
||||
mapTopic: true
|
||||
versions:
|
||||
free-pro-team: '*'
|
||||
enterprise-server: '*'
|
||||
github-ae: '*'
|
||||
topics:
|
||||
- pages
|
||||
---
|
||||
|
||||
@@ -1,61 +0,0 @@
|
||||
---
|
||||
title: Testing your GitHub Pages site locally with Jekyll
|
||||
intro: 'You can build your {% data variables.product.prodname_pages %} site locally to preview and test changes to your site.'
|
||||
redirect_from:
|
||||
- /articles/setting-up-your-pages-site-locally-with-jekyll/
|
||||
- /articles/setting-up-your-github-pages-site-locally-with-jekyll/
|
||||
- /articles/testing-your-github-pages-site-locally-with-jekyll
|
||||
product: '{% data reusables.gated-features.pages %}'
|
||||
versions:
|
||||
free-pro-team: '*'
|
||||
enterprise-server: '*'
|
||||
github-ae: '*'
|
||||
topics:
|
||||
- pages
|
||||
---
|
||||
|
||||
Anyone with read permissions for a repository can test a {% data variables.product.prodname_pages %} site locally.
|
||||
|
||||
### Prerequisites
|
||||
|
||||
Before you can use Jekyll to test a site, you must:
|
||||
- Install [Jekyll](https://jekyllrb.com/docs/installation/).
|
||||
- Create a Jekyll site. For more information, see "[Creating a {% data variables.product.prodname_pages %} site with Jekyll](/articles/creating-a-github-pages-site-with-jekyll)."
|
||||
|
||||
{% data reusables.pages.recommend-bundler %}
|
||||
|
||||
{% data reusables.pages.jekyll-install-troubleshooting %}
|
||||
|
||||
### Building your site locally
|
||||
|
||||
{% data reusables.command_line.open_the_multi_os_terminal %}
|
||||
{% data reusables.pages.navigate-publishing-source %}
|
||||
3. Run `bundle install`.
|
||||
3. Run your Jekyll site locally.
|
||||
```shell
|
||||
$ bundle exec jekyll serve
|
||||
> Configuration file: /Users/octocat/my-site/_config.yml
|
||||
> Source: /Users/octocat/my-site
|
||||
> Destination: /Users/octocat/my-site/_site
|
||||
> Incremental build: disabled. Enable with --incremental
|
||||
> Generating...
|
||||
> done in 0.309 seconds.
|
||||
> Auto-regeneration: enabled for '/Users/octocat/my-site'
|
||||
> Configuration file: /Users/octocat/my-site/_config.yml
|
||||
> Server address: http://127.0.0.1:4000/
|
||||
> Server running... press ctrl-c to stop.
|
||||
```
|
||||
3. To preview your site, in your web browser, navigate to `http://localhost:4000`.
|
||||
|
||||
### Updating the {% data variables.product.prodname_pages %} gem
|
||||
|
||||
Jekyll is an active open source project that is updated frequently. If the `github-pages` gem on your computer is out of date with the `github-pages` gem on the {% data variables.product.prodname_pages %} server, your site may look different when built locally than when published on {% data variables.product.product_name %}. To avoid this, regularly update the `github-pages` gem on your computer.
|
||||
|
||||
{% data reusables.command_line.open_the_multi_os_terminal %}
|
||||
2. Update the `github-pages` gem.
|
||||
- If you installed Bundler, run `bundle update github-pages`.
|
||||
- If you don't have Bundler installed, run `gem update github-pages`.
|
||||
|
||||
### Further reading
|
||||
|
||||
- [{% data variables.product.prodname_pages %}](http://jekyllrb.com/docs/github-pages/) in the Jekyll documentation
|
||||
@@ -1,64 +0,0 @@
|
||||
---
|
||||
title: Troubleshooting custom domains and GitHub Pages
|
||||
intro: 'You can check for common errors to resolve issues with custom domains or HTTPS for your {% data variables.product.prodname_pages %} site.'
|
||||
redirect_from:
|
||||
- /articles/my-custom-domain-isn-t-working/
|
||||
- /articles/custom-domain-isn-t-working/
|
||||
- /articles/troubleshooting-custom-domains/
|
||||
- /articles/troubleshooting-custom-domains-and-github-pages
|
||||
product: '{% data reusables.gated-features.pages %}'
|
||||
versions:
|
||||
free-pro-team: '*'
|
||||
topics:
|
||||
- pages
|
||||
---
|
||||
|
||||
### _CNAME_ errors
|
||||
|
||||
Custom domains are stored in a _CNAME_ file in the root of your publishing source. You can add or update this file through your repository settings or manually. For more information, see "[Managing a custom domain for your {% data variables.product.prodname_pages %} site](/articles/managing-a-custom-domain-for-your-github-pages-site)."
|
||||
|
||||
For your site to render at the correct domain, make sure your _CNAME_ file still exists in the repository. For example, many static site generators force push to your repository, which can overwrite the _CNAME_ file that was added to your repository when you configured your custom domain. If you build your site locally and push generated files to {% data variables.product.product_name %}, make sure to pull the commit that added the _CNAME_ file to your local repository first, so the file will be included in the build.
|
||||
|
||||
Then, make sure the _CNAME_ file is formatted correctly.
|
||||
|
||||
- The _CNAME_ filename must be all uppercase.
|
||||
- The _CNAME_ file can contain only one domain. To point multiple domains to your site, you must set up a redirect through your DNS provider.
|
||||
- The _CNAME_ file must contain the domain name only. For example, `www.example.com`, `blog.example.com`, or `example.com`.
|
||||
- The domain name must be unique across all {% data variables.product.prodname_pages %} sites. For example, if another repository's _CNAME_ file contains `example.com`, you cannot use `example.com` in the _CNAME_ file for your repository.
|
||||
|
||||
### DNS misconfiguration
|
||||
|
||||
If you have trouble pointing the default domain for your site to your custom domain, contact your DNS provider.
|
||||
|
||||
You can also test whether your custom domain's DNS records are configured correctly. For more information, see "[Managing a custom domain for your {% data variables.product.prodname_pages %} site](/articles/managing-a-custom-domain-for-your-github-pages-site)."
|
||||
|
||||
### Custom domain names that are unsupported
|
||||
|
||||
If your custom domain is unsupported, you may need to change your domain to a supported domain. You can also contact your DNS provider to see if they offer forwarding services for domain names.
|
||||
|
||||
Make sure your site does not:
|
||||
- Use more than one apex domain. For example, both `example.com` and `anotherexample.com`.
|
||||
- Use more than one `www` subdomain. For example, both `www.example.com` and `www.anotherexample.com`.
|
||||
- Use both an apex domain and custom subdomain. For example, both `example.com` and `docs.example.com`.
|
||||
|
||||
The one exception is the `www` subdomain. If configured correctly, the `www` subdomain is automatically redirected to the apex domain. For more information, see "[Managing a custom domain for your {% data variables.product.prodname_pages %} site](/github/working-with-github-pages/managing-a-custom-domain-for-your-github-pages-site#configuring-an-apex-domain)."
|
||||
|
||||
{% data reusables.pages.wildcard-dns-warning %}
|
||||
|
||||
For a list of supported custom domains, see "[About custom domains and {% data variables.product.prodname_pages %}](/articles/about-custom-domains-and-github-pages/#supported-custom-domains)."
|
||||
|
||||
### HTTPS errors
|
||||
|
||||
{% data variables.product.prodname_pages %} sites using custom domains that are correctly configured with _CNAME_, `ALIAS`, `ANAME`, or `A` DNS records can be accessed over HTTPS. For more information, see "[Securing your {% data variables.product.prodname_pages %} site with HTTPS](/articles/securing-your-github-pages-site-with-https)."
|
||||
|
||||
It can take up to an hour for your site to become available over HTTPS after you configure your custom domain. After you update existing DNS settings, you may need to remove and re-add your custom domain to your site's repository to trigger the process of enabling HTTPS. For more information, see "[Managing a custom domain for your {% data variables.product.prodname_pages %} site](/articles/managing-a-custom-domain-for-your-github-pages-site)."
|
||||
|
||||
If you're using Certification Authority Authorization (CAA) records, at least one CAA record must exist with the value `letsencrypt.org` for your site to be accessible over HTTPS. For more information, see "[Certificate Authority Authorization (CAA)](https://letsencrypt.org/docs/caa/)" in the Let's Encrypt documentation.
|
||||
|
||||
### URL formatting on Linux
|
||||
|
||||
If the URL for your site contains a username or organization name that begins or ends with a dash, or contains consecutive dashes, people browsing with Linux will receive a server error when they attempt to visit your site. To fix this, change your {% data variables.product.product_name %} username to remove non-alphanumeric characters. For more information, see "[Changing your {% data variables.product.prodname_dotcom %} username](/articles/changing-your-github-username/)."
|
||||
|
||||
### Browser cache
|
||||
|
||||
If you've recently changed or removed your custom domain and can't access the new URL in your browser, you may need to clear your browser's cache to reach the new URL. For more information on clearing your cache, see your browser's documentation.
|
||||
@@ -1,190 +0,0 @@
|
||||
---
|
||||
title: Troubleshooting Jekyll build errors for GitHub Pages sites
|
||||
intro: 'You can use Jekyll build error messages to troubleshoot problems with your {% data variables.product.prodname_pages %} site.'
|
||||
redirect_from:
|
||||
- /articles/page-build-failed-missing-docs-folder/
|
||||
- /articles/page-build-failed-invalid-submodule/
|
||||
- /articles/page-build-failed-missing-submodule/
|
||||
- /articles/page-build-failed-markdown-errors/
|
||||
- /articles/page-build-failed-config-file-error/
|
||||
- /articles/page-build-failed-unknown-tag-error/
|
||||
- /articles/page-build-failed-tag-not-properly-terminated/
|
||||
- /articles/page-build-failed-tag-not-properly-closed/
|
||||
- /articles/page-build-failed-file-does-not-exist-in-includes-directory/
|
||||
- /articles/page-build-failed-file-is-a-symlink/
|
||||
- /articles/page-build-failed-symlink-does-not-exist-within-your-sites-repository/
|
||||
- /articles/page-build-failed-file-is-not-properly-utf-8-encoded/
|
||||
- /articles/page-build-failed-invalid-post-date/
|
||||
- /articles/page-build-failed-invalid-sass-or-scss/
|
||||
- /articles/page-build-failed-invalid-highlighter-language/
|
||||
- /articles/page-build-failed-relative-permalinks-configured/
|
||||
- /articles/page-build-failed-syntax-error-in-for-loop/
|
||||
- /articles/page-build-failed-invalid-yaml-in-data-file/
|
||||
- /articles/page-build-failed-date-is-not-a-valid-datetime/
|
||||
- /articles/troubleshooting-github-pages-builds/
|
||||
- /articles/troubleshooting-jekyll-builds/
|
||||
- /articles/troubleshooting-jekyll-build-errors-for-github-pages-sites
|
||||
product: '{% data reusables.gated-features.pages %}'
|
||||
versions:
|
||||
free-pro-team: '*'
|
||||
enterprise-server: '*'
|
||||
github-ae: '*'
|
||||
topics:
|
||||
- pages
|
||||
---
|
||||
|
||||
### Troubleshooting build errors
|
||||
|
||||
If Jekyll encounters an error building your {% data variables.product.prodname_pages %} site locally or on {% data variables.product.product_name %}, you can use error messages to troubleshoot. For more information about error messages and how to view them, see "[About Jekyll build errors for {% data variables.product.prodname_pages %} sites](/articles/about-jekyll-build-errors-for-github-pages-sites)."
|
||||
|
||||
If you received a generic error message, check for common issues.
|
||||
- You're using unsupported plugins. For more information, see "[About {% data variables.product.prodname_pages %} and Jekyll](/articles/about-github-pages-and-jekyll#plugins)."{% if currentVersion == "free-pro-team@latest" %}
|
||||
- Your repository has exceeded our repository size limits. For more information, see "[What is my disk quota?](/articles/what-is-my-disk-quota)"{% endif %}
|
||||
- You changed the `source` setting in your *_config.yml* file. {% data variables.product.prodname_pages %} overrides this setting during the build process.
|
||||
- A filename in your publishing source contains a colon (`:`) which is not supported.
|
||||
|
||||
If you received a specific error message, review the troubleshooting information for the error message below.
|
||||
|
||||
After you've fixed any errors, push the changes to your site's publishing source to trigger another build on {% data variables.product.product_name %}.
|
||||
|
||||
### Config file error
|
||||
|
||||
This error means that your site failed to build because the *_config.yml* file contains syntax errors.
|
||||
|
||||
To troubleshoot, make sure that your *_config.yml* file follows these rules:
|
||||
|
||||
{% data reusables.pages.yaml-rules %}
|
||||
|
||||
{% data reusables.pages.yaml-linter %}
|
||||
|
||||
### Date is not a valid datetime
|
||||
|
||||
This error means that one of the pages on your site includes an invalid datetime.
|
||||
|
||||
To troubleshoot, search the file in the error message and the file's layouts for calls to any date-related Liquid filters. Make sure that any variables passed into date-related Liquid filters have values in all cases and never pass `nil` or `""`. For more information, see "[Liquid filters](https://help.shopify.com/en/themes/liquid/filters)" in the Liquid documentation.
|
||||
|
||||
### File does not exist in includes directory
|
||||
|
||||
This error means that your code references a file that doesn't exist in your *_includes* directory.
|
||||
|
||||
{% data reusables.pages.search-for-includes %} If any of the files you've referenced aren't in the *_includes* directory, copy or move the files into the *_includes* directory.
|
||||
|
||||
### File is a symlink
|
||||
|
||||
This error means that your code references a symlinked file that does not exist in the publishing source for your site.
|
||||
|
||||
{% data reusables.pages.search-for-includes %} If any of the files you've referenced are symlinked, copy or move the files into the *_includes* directory.
|
||||
|
||||
### File is not properly UTF-8 encoded
|
||||
|
||||
This error means that you used non-Latin characters, like `日本語`, without telling the computer to expect these symbols.
|
||||
|
||||
To troubleshoot, force UTF-8 encoding by adding the following line to your *_config.yml* file:
|
||||
```yaml
|
||||
encoding: UTF-8
|
||||
```
|
||||
|
||||
### Invalid highlighter language
|
||||
|
||||
This error means that you specified any syntax highlighter other than [Rouge](https://github.com/jneen/rouge) or [Pygments](http://pygments.org/) in your configuration file.
|
||||
|
||||
To troubleshoot, update your *_config.yml* file to specify [Rouge](https://github.com/jneen/rouge) or [Pygments](http://pygments.org/). For more information, see "[About {% data variables.product.product_name %} and Jekyll](/articles/about-github-pages-and-jekyll#syntax-highlighting)."
|
||||
|
||||
### Invalid post date
|
||||
|
||||
This error means that a post on your site contains an invalid date in the filename or YAML front matter.
|
||||
|
||||
To troubleshoot, make sure all dates are formatted as YYYY-MM-DD HH:MM:SS for UTC and are actual calendar dates. To specify a time zone with an offset from UTC, use the format YYYY-MM-DD HH:MM:SS +/-TTTT, like `2014-04-18 11:30:00 +0800`.
|
||||
|
||||
If you specify a date format in your *_config.yml* file, make sure the format is correct.
|
||||
|
||||
### Invalid Sass or SCSS
|
||||
|
||||
This error means your repository contains a Sass or SCSS file with invalid content.
|
||||
|
||||
To troubleshoot, review the line number included in the error message for invalid Sass or SCSS. To help prevent future errors, install a Sass or SCSS linter for your favorite text editor.
|
||||
|
||||
### Invalid submodule
|
||||
|
||||
This error means that your repository includes a submodule that hasn't been properly initialized.
|
||||
|
||||
{% data reusables.pages.remove-submodule %}
|
||||
|
||||
If do you want to use the submodule, make sure you use `https://` when referencing the submodule (not `http://`) and that the submodule is in a public repository.
|
||||
|
||||
### Invalid YAML in data file
|
||||
|
||||
This error means that one of more files in the *_data* folder contains invalid YAML.
|
||||
|
||||
To troubleshoot, make sure the YAML files in your *_data* folder follow these rules:
|
||||
|
||||
{% data reusables.pages.yaml-rules %}
|
||||
|
||||
{% data reusables.pages.yaml-linter %}
|
||||
|
||||
For more information about Jekyll data files, see "[Data Files](https://jekyllrb.com/docs/datafiles/)" in the Jekyll documentation.
|
||||
|
||||
### Markdown errors
|
||||
|
||||
This error means that your repository contains Markdown errors.
|
||||
|
||||
To troubleshoot, make sure you are using a supported Markdown processor. For more information, see "[Setting a Markdown processor for your {% data variables.product.prodname_pages %} site using Jekyll](/articles/setting-a-markdown-processor-for-your-github-pages-site-using-jekyll)."
|
||||
|
||||
Then, make sure the file in the error message uses valid Markdown syntax. For more information, see "[Markdown: Syntax](https://daringfireball.net/projects/markdown/syntax)" on Daring Fireball.
|
||||
|
||||
### Missing docs folder
|
||||
|
||||
This error means that you have chosen the `docs` folder on a branch as your publishing source, but there is no `docs` folder in the root of your repository on that branch.
|
||||
|
||||
To troubleshoot, if your `docs` folder was accidentally moved, try moving the `docs` folder back to the root of your repository on the branch you chose for your publishing source. If the `docs` folder was accidentally deleted, you can either:
|
||||
- Use Git to revert or undo the deletion. For more information, see "[git-revert](https://git-scm.com/docs/git-revert.html)" in the Git documentation.
|
||||
- Create a new `docs` folder in the root of your repository on the branch you chose for your publishing source and add your site's source files to the folder. For more information, see "[Creating new files](/articles/creating-new-files)."
|
||||
- Change your publishing source. For more information, see "[Configuring a publishing source for {% data variables.product.prodname_pages %}](/articles/configuring-a-publishing-source-for-github-pages)."
|
||||
|
||||
### Missing submodule
|
||||
|
||||
This error means that your repository includes a submodule that doesn't exist or hasn't been properly initialized.
|
||||
|
||||
{% data reusables.pages.remove-submodule %}
|
||||
|
||||
If you do want to use a submodule, initialize the submodule. For more information, see "[Git Tools - Submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules)" in the _Pro Git_ book.
|
||||
|
||||
### Relative permalinks configured
|
||||
|
||||
This errors means that you have relative permalinks, which are not supported by {% data variables.product.prodname_pages %}, in your *_config.yml* file.
|
||||
|
||||
Permalinks are permanent URLs that reference a particular page on your site. Absolute permalinks begin with the root of the site, while relative permalinks begin with the folder containing the referenced page. {% data variables.product.prodname_pages %} and Jekyll no longer support relative permalinks. For more information about permalinks, see "[Permalinks](https://jekyllrb.com/docs/permalinks/)" in the Jekyll documentation.
|
||||
|
||||
To troubleshoot, remove the `relative_permalinks` line from your *_config.yml* file and reformat any relative permalinks in your site with absolute permalinks. For more information, see "[Editing files in your repository](/articles/editing-files-in-your-repository)."
|
||||
|
||||
### Symlink does not exist within your site's repository
|
||||
|
||||
This error means that your site includes a symbolic link (symlink) that does not exist in the publishing source for your site. For more information about symlinks, see "[Symbolic link](https://en.wikipedia.org/wiki/Symbolic_link)" on Wikipedia.
|
||||
|
||||
To troubleshoot, determine if the file in the error message is used to build your site. If not, or if you don't want the file to be a symlink, delete the file. If the symlinked file is necessary to build your site, make sure the file or directory the symlink references is in the publishing source for your site. To include external assets, consider using {% if currentVersion == "free-pro-team@latest" %}`git submodule` or {% endif %}a third-party package manager such as [Bower](https://bower.io/).{% if currentVersion == "free-pro-team@latest" %} For more information, see "[Using submodules with {% data variables.product.prodname_pages %}](/articles/using-submodules-with-github-pages)."{% endif %}
|
||||
|
||||
### Syntax error in 'for' loop
|
||||
|
||||
This error means that your code includes invalid syntax in a Liquid `for` loop declaration.
|
||||
|
||||
To troubleshoot, make sure all `for` loops in the file in the error message have proper syntax. For more information about proper syntax for `for` loops, see "[Iteration tags](https://help.shopify.com/en/themes/liquid/tags/iteration-tags#for)" in the Liquid documentation.
|
||||
|
||||
### Tag not properly closed
|
||||
|
||||
This error message means that your code includes a logic tag that is not properly closed. For example, {% raw %}`{% capture example_variable %}` must be closed by `{% endcapture %}`{% endraw %}.
|
||||
|
||||
To troubleshoot, make sure all logic tags in the file in the error message are properly closed. For more information, see "[Liquid tags](https://help.shopify.com/en/themes/liquid/tags)" in the Liquid documentation.
|
||||
|
||||
### Tag not properly terminated
|
||||
|
||||
This error means that your code includes an output tag that is not properly terminated. For example, {% raw %}`{{ page.title }` instead of `{{ page.title }}`{% endraw %}.
|
||||
|
||||
To troubleshoot, make sure all output tags in the file in the error message are terminated with `}}`. For more information, see "[Liquid objects](https://help.shopify.com/en/themes/liquid/objects)" in the Liquid documentation.
|
||||
|
||||
### Unknown tag error
|
||||
|
||||
This error means that your code contains an unrecognized Liquid tag.
|
||||
|
||||
To troubleshoot, make sure all Liquid tags in the file in the error message match Jekyll's default variables and there are no typos in the tag names. For a list of default variables, see "[Variables](https://jekyllrb.com/docs/variables/)" in the Jekyll documentation.
|
||||
|
||||
Unsupported plugins are a common source of unrecognized tags. If you use an unsupported plugin in your site by generating your site locally and pushing your static files to {% data variables.product.product_name %}, make sure the plugin is not introducing tags that are not in Jekyll's default variables. For a list of supported plugins, see "[About {% data variables.product.prodname_pages %} and Jekyll](/articles/about-github-pages-and-jekyll#plugins)."
|
||||
@@ -1,34 +0,0 @@
|
||||
---
|
||||
title: Unpublishing a GitHub Pages site
|
||||
intro: 'You can unpublish your {% data variables.product.prodname_pages %} site so that the site is no longer available.'
|
||||
redirect_from:
|
||||
- /articles/how-do-i-unpublish-a-project-page/
|
||||
- /articles/unpublishing-a-project-page/
|
||||
- /articles/unpublishing-a-project-pages-site/
|
||||
- /articles/unpublishing-a-user-pages-site/
|
||||
- /articles/unpublishing-a-github-pages-site
|
||||
product: '{% data reusables.gated-features.pages %}'
|
||||
permissions: 'People with admin or maintainer permissions for a repository can unpublish a {% data variables.product.prodname_pages %} site.'
|
||||
versions:
|
||||
free-pro-team: '*'
|
||||
enterprise-server: '*'
|
||||
github-ae: '*'
|
||||
topics:
|
||||
- pages
|
||||
---
|
||||
|
||||
### Unpublishing a project site
|
||||
|
||||
{% data reusables.repositories.navigate-to-repo %}
|
||||
2. If a `gh-pages` branch exists in the repository, delete the `gh-pages` branch. For more information, see "[Creating and deleting branches within your repository](/articles/creating-and-deleting-branches-within-your-repository#deleting-a-branch)."
|
||||
3. If the `gh-pages` branch was your publishing source, {% if currentVersion == "free-pro-team@latest" %}skip to step 6{% else %}your site is now unpublished and you can skip the remaining steps{% endif %}.
|
||||
{% data reusables.repositories.sidebar-settings %}
|
||||
5. Under "{% data variables.product.prodname_pages %}", use the **Source** drop-down menu and select **None.**
|
||||
|
||||
{% data reusables.pages.update_your_dns_settings %}
|
||||
|
||||
### Unpublishing a user or organization site
|
||||
|
||||
{% data reusables.repositories.navigate-to-repo %}
|
||||
2. Delete the branch that you're using as a publishing source, or delete the entire repository. For more information, see "[Creating and deleting branches within your repository](/articles/creating-and-deleting-branches-within-your-repository#deleting-a-branch)" and "[Deleting a repository](/articles/deleting-a-repository)."
|
||||
{% data reusables.pages.update_your_dns_settings %}
|
||||
@@ -1,23 +0,0 @@
|
||||
---
|
||||
title: Using submodules with GitHub Pages
|
||||
intro: 'You can use submodules with {% data variables.product.prodname_pages %} to include other projects in your site''s code.'
|
||||
redirect_from:
|
||||
- /articles/using-submodules-with-pages/
|
||||
- /articles/using-submodules-with-github-pages
|
||||
product: '{% data reusables.gated-features.pages %}'
|
||||
versions:
|
||||
free-pro-team: '*'
|
||||
topics:
|
||||
- pages
|
||||
---
|
||||
|
||||
If the repository for your {% data variables.product.prodname_pages %} site contains submodules, their contents will automatically be pulled in when your site is built.
|
||||
|
||||
You can only use submodules that point to public repositories, because the {% data variables.product.prodname_pages %} server cannot access private repositories.
|
||||
|
||||
Use the `https://` read-only URL for your submodules, including nested submodules. You can make this change in your _.gitmodules_ file.
|
||||
|
||||
### Further reading
|
||||
|
||||
- "[Git Tools - Submodules](https://git-scm.com/book/en/Git-Tools-Submodules)" from the _Pro Git_ book
|
||||
- "[Troubleshooting Jekyll build errors for {% data variables.product.prodname_pages %} sites](/articles/troubleshooting-jekyll-build-errors-for-github-pages-sites)"
|
||||
Reference in New Issue
Block a user