Publishing with GitHub Pages, now as easy as 1, 2, 3

Publishing a website or software documentation with GitHub Pages now requires far fewer steps — three to be exact:

  1. Create a repository (or navigate to an existing repository)
  2. Commit a Markdown file via the web interface, just like you would any other file
  3. Activate GitHub Pages via your repository's settings

And that's it — you now have a website. If you're already familiar with GitHub Pages, you may be interested to know that behind the scenes, we're now doing a few things to simplify the publishing experience and bring it more in line with what you may expect from authoring Markdown content elsewhere on GitHub:

  1. All Markdown files are now rendered by GitHub Pages, saving you from needing to add YAML front matter (the metadata at the top of the file separated by ---s) to each file.
  2. We'll use your README file as the site's index if you don't have an index.md (or index.html), not dissimilar from when you browse to a repository on GitHub.
  3. If you don't specify a theme in your site's config (or don't have a config file at all), we'll set a minimal, default theme that matches the look and feel of Markdown elsewhere on GitHub.
  4. If a given file doesn't have a layout specified, we'll assign one based on its context. For example, pages will automatically get the page layout, or the default layout, if the page layout doesn't exist.
  5. If your page doesn't have an explicit title, and the file begins with an H1, H2, or H3, we'll use that heading as the page's title, which appears in places like browser tabs.

These improvements should allow you to quickly and easily publish your first (or 100th) website with just a few clicks, or to document your software project by simply adding Markdown files to a /docs folder within your repository. Of course, you can continue to control the look and feel by opting in to additional customizations (such as overriding the default theme with your own layouts or styles).

While these changes shouldn't affect how most existing sites build, there are two potential gotchas for some more advanced Jekyll users:

  1. If your site iterates through all pages (e.g., for page in site.pages), you may find that there are now additional pages (such as the README of a vendored dependency) in that list. You can explicitly exclude these files with your config file's exclude directive.
  2. If you don't specify a page's layout or title, and expect either to be unset (e.g., if you need to serve unstyled content), you'll need to explicitly set those values as null.

And if for any reason you don't want these features, you can disable them by adding a .nojekyll file to your site's root directory.

So that the GitHub Pages build process can be as transparent and customizable as possible, all the above features are implemented as open source Jekyll plugins, namely Jekyll Optional Front Matter, Jekyll README Index, Jekyll Default Layout, and Jekyll Titles from Headings.

Again, these changes shouldn't affect how most existing sites build (although you can safely begin to use these features), but if you have any questions, please get in touch with us.

Happy three-step publishing!

Introducing review requests

You can now request a review explicitly from collaborators, making it easier to specify who you'd like to review your pull request.

You can also see a list of people who you are awaiting review from in the pull request page sidebar, as well as the status of reviews from those who have already left them.

gif of requesting review from sidebar

Pending requests for review will also show in the merge box. They do not affect mergability, however, so you can still merge your pull request even if you are still awaiting review from another collaborator.

image of merge box showing a requested review

Learn more about requesting reviews in our Help docs.

Relative links for GitHub pages

You've been able to use relative links when authoring Markdown on GitHub.com for a while. Now, those links will continue to work when published via GitHub Pages.

If you have a Markdown file in your repository at docs/page.md, and you want to link from that file to docs/another-page.md, you can do so with the following markup:

[a relative link](another-page.md)

When you view the source file on GitHub.com, the relative link will continue to work, as it has before, but now, when you publish that file using GitHub Pages, the link will be silently translated to docs/another-page.html to match the target page's published URL.

Under the hood, we're using the open source Jekyll Relative Links plugin, which is activated by default for all builds.

Relative links on GitHub Pages also take into account custom permalinks (e.g., permalink: /docs/page/) in a file's YAML front matter, as well as prepend project pages' base URL as appropriate, ensuring links continue to work in any context.

Happy (consistent) publishing!

GitHub Extension now supports Visual Studio 2017 RC

The GitHub Extension for Visual Studio now supports Visual Studio 2017 RC, including support for cloning repositories directly from the Visual Studio Start Page. We've also improved our startup time to get you productive as fast as possible.

This release, version 2.1.1.0, is available as an optional installation component in the installer for both Visual Studio 2015 and Visual Studio 2017 RC. You can also install it directly from the Visual Studio gallery or download it from visualstudio.github.com.

Last year we introduced the GitHub Extension for Visual Studio as an open source project under the MIT license. You can log issues and contribute to the extension in the repository.

Clone from GitHub on Start Page

What's new in GitHub Pages with Jekyll 3.3

GitHub Pages has upgraded to Jekyll 3.3.0, a release with some nice quality-of-life features.

First, Jekyll 3.3 introduces two new convenience filters, relative_url and absolute_url. They provide an easy way to ensure that your site's URLs will always appear correctly, regardless of where or how your site is viewed. To make it easier to use these two new filters, GitHub Pages now automatically sets the site.url and site.baseurl properties, if they're not already set.

This means that starting today {{ "/about/" | relative_url }} will produce /repository-name/about/ for Project Pages (and /about/ for User Pages). Additionally, {{ "/about/" | absolute_url }} will produce https://baxterthehacker.github.io/repository-name/about/ for Project Pages (and https://baxterthehacker.github.io/about/ for User Pages or http://example.com/about/ if you have a custom domain set up).

Second, with Jekyll 3.3, when you run jekyll serve in development, it will override your url value with http://localhost:4000. No more confusion when your locally-modified CSS isn't loading because the URL is set to the production site. Additionally, site.url and absolute_url will now yield http://localhost:4000 when running a server locally.

Finally, to make it easier to vendor third-party dependencies via package managers like Bundler or NPM (or Yarn), Jekyll now ignores the vendor and node_modules directories by default, speeding up build times and avoiding potential errors. If you need those directories included in your site, set exclude: [] in your site's configuration file.

For more information, see the Jekyll changelog and if you have any questions, please let us know.

Happy publishing!

Introducing Projects for Organizations

You can now use GitHub Projects at the Organization level. All users in your Organization will have access to its Projects, so you and your team can plan and manage work across repositories. With organization-wide Projects, everyone can see what's already in motion and work together without duplicating efforts.

Projects for Organizations

Organization-wide projects can contain issues and pull requests from any repository that belongs to an organization. If an organization-wide project includes issues or pull requests from a repository that you don't have permission to view, you won't be able to see it.

Projects launched in September 2016. Check out the documentation to see how you can use them, and stay tuned—there's more to come.

Dismissing reviews on Pull Requests

Dismiss reviews on GitHub

Pull request reviews are a great way to share the weight of building software. Using protected branches to block merging when pull requests have reviews that request changes helps your team maintain quality, bug-free code. However, this requirement can sometimes block your team’s progress without good reason. If someone leaves a review that requests changes and then goes on vacation or runs into computer problems, your pull request could be blocked for days, even after you’ve addressed the reviewer’s concerns.

To improve this workflow, we’re adding the ability for pull request collaborators to dismiss reviews. When someone leaves a review that requests changes, dismissing the review changes it from a review that requests changes to a review comment. This will unblock your pull request, freeing you up to merge it!

You can also dismiss an approving review. This is useful when your pull request has changed significantly since the approval, and you think it’s important to get another review.

When one of your team members dismisses a review, they’ll have to leave a reason why. This keeps people from simply bypassing the protected branch review requirement out of convenience.

Rebase and merge pull requests

The merge button on pull requests supports two great workflows
with merge commits and commit squashing.
Now you can use the merge button to rebase and merge your changes, too.

Rebase

How does it work?

When you select the new "Rebase and merge" option,
the commits from the pull request's branch are rebased on to the tip
of the base branch, and then the base branch itself is fast forwarded
to this newly rebased head. Rebases automatically set the committer of
the rebased commits to the current user, while keeping authorship
information intact.
The pull request's branch will not be modified by this operation.

If a rebase can't be performed due to conflicts, we'll let you know so
you can manually resolve them as necessary.

Rebase with conflicts

As with "Squash and merge", repository administrators can decide whether they
want to allow this new option on the repository settings page.

Learn more about rebase and merge in our Help docs.

License now displayed on repository overview

Licenses are now displayed in the repository overview, allowing anyone to easily see if a project has an open source license. This change is immediately available on GitHub, and will also ship with the upcoming Enterprise 2.8 release.

A shortened license name, linking to the repository’s license file, is displayed on the repository page:

screenshot

We use an open source Ruby gem called Licensee to compare the repository's LICENSE file to a short list of known licenses. This is the same code we use to provide the Licenses API and understand how repositories on GitHub are licensed.

We don’t detect every open source license, nor complicated situations such as projects with multiple licenses. For those situations you can still find and read the project’s license(s) as before.

Open source is a fundamental part of GitHub’s community. Adding an open source license to your repository ensures that others can use, copy, modify, and contribute back to your project. It's an important step when creating an open source project. If your repository doesn’t have an open source license and you want others to get involved, consider adding one now.

A whole new GitHub Universe: announcing new tools, forums, and features

Today I welcomed more than 1,500 people to our second annual Universe conference in San Francisco, an event designed to celebrate the people building the future of software. It’s an important reminder about who we’re here for—whether it’s the open source maintainer whose project is transforming healthcare, an automotive company building a self-driving car, or a teenager teaching herself how to program after she finishes her homework.

Our goal is to make building software easier for you. And with that goal in sight, we’re announcing our biggest update to the platform yet. We’re making it easier for you to work together to ship high-quality code through improved code review tools, and we’re giving our profiles an update to better show who you are as a developer. We’re making integrating with GitHub a first class experience through major API improvements. And we’re taking steps toward making GitHub a better place for businesses to get work done with added security measures for organizations.

I’m proud of our team for coming together to ship so many improvements to the platform, and I hope you’ll find them useful as you continue to build amazing things. Read on for more specifics, and keep an eye out for continued improvements to your GitHub experience in the coming months.

Manage your ideas with Projects

Taking projects from idea to launch isn’t easy. There’s a lot to coordinate behind the scenes, and so many tools out there to help you organize and distribute work. To help you integrate project management into your development cycle without skipping a beat (or even opening a new browser tab), we’re introducing Projects.

Projects

With Projects, you can manage work directly from your GitHub repositories. Create cards from Pull Requests, Issues or Notes and organize them into custom columns, whether it’s "In-progress," "Done," "Never going to happen" or any other framework your team uses. Drag and drop the cards inside a column to prioritize them or move them from one column to another as your work progresses. And with Notes, you can capture every early idea that comes up as part of your standup or team sync, without polluting your list of issues. For more on what's changed, watch this quick overview.

Although we’ll quickly be adding to Projects, our initial release currently supports:

  • A New Projects tab–at the same level as Code, Issue, Pull Requests within a repository–that lists all of your projects
  • Workflow columns that you can name and reorder
  • Cards that you can drag and drop between columns pointing to issues, Pull Requests, or notes
  • Tools built on top of Projects by some fantastic partners, including Waffle.io and ZenHub

Code better with Reviews

Collaboration is the core of building great software—and code review is critical to collaboration. When another person looks at your code and gives it the same level of critique that you did while writing it, your work gets better. We’re improving code review on GitHub to help you share the weight of building software and improve the software you build.

GitHub code review

Designing the best way for you to review code is a continuous process, but our first step is now available on all pull requests—Reviews. In addition to commenting on specific lines of code, Reviews let you formally “approve” or “request changes” to pull requests. You can also leave a review summary and delete, edit, or bundle comments before you submit them.

Reviewing code changes

To streamline conversations and cut down on noise, you can reply to inline comments without drafting a formal review or starting a new conversation. This also means you can have multiple conversations per line of code—creating more explicit feedback loops, smarter conversations, and better code review.

Finally, administrators can require Reviews before merging via protected branches. When Reviews are required, you must have a least one approval and no changes requested before you can merge.

Blocked Pull Request

These changes are only the first step of a much greater roadmap toward faster, friendlier code reviews. We’re working on a handful of follow-up feature improvements—including the ability to request reviews from your peers. For more information on Reviews, including what we’ve shipped today, check out the documentation or a quick tutorial video on Reviews.

Integrate seamlessly with GitHub

Developers use a variety of tools to ship their software and we’ve seen hundreds of integrations built to work with GitHub. Now we’re shipping some major improvements to our API and adding new ways to collaborate transparently not only with GitHub engineers but also the broader community of integrators. As host to the largest community of developers, we want to make the GitHub platform uniquely enjoyable for integrators to build applications that change how people work. Here’s what we’re launching right away:

  • A public Platform Roadmap that demonstrates what GitHub Platform Engineers are launching next and why
  • A formalized process to solicit feedback and launch updates to our platform
  • Early-access and pre-release programs that let you access new features and APIs and provide you with the support you need to ensure launch readiness for the software you build on top of GitHub
  • The GitHub Platform Forum which provides a direct communication channel between ecosystem developers and GitHub engineers.

With that, we are excited to announce two new projects that aim to make our platform more flexible:

Integrations Early Access

We’re rethinking our integrations model to provide better ways for tools to extend and integrate with GitHub. We’ve added the ability for an integration to act on its own behalf instead of impersonating a user—making it a first class actor on GitHub without using a paid seat. Admins will have the ability to configure integrations directly on Organizations and control which repositories they allow access to. Read more about Integrations on our Developer Blog or check out the documentation.

The GitHub GraphQL API Early Access

The GraphQL API simplifies your product development by letting developers access all the data they need, and only the data they need, with one API call. With the GitHub GraphQL API, you get the same API we use to build GitHub features. To learn more and see how it works, check out our Engineering Blog.

Have a friendlier business experience on GitHub.com

Organizations on GitHub are the best way for teams of developers to build and ship software together, and with the added security of two-factor authentication enforcement and upcoming product enhancements, they’ve never been better.

Easily enforce security

Now Organization administrators can require two-factor authentication for all members—making it easier to support security policies.

Enforced two-factor authentication in an organization

Admins will be asked to confirm the two-factor authentication requirement and a confirmation modal will list members and forks that will be removed as a result. GitHub will notify members if they’re being removed from an organization with email and in-product notifications. Finally, as always, admins can invite members back with their forks and settings intact once their security is up to speed. Read more about requiring two-factor authentication in your organization.

Take greater control over your permissions

Over the last few years, we’ve rolled out LDAP and CAS to securely and efficiently manage permissions on GitHub Enterprise. Now we’re making sure businesses on GitHub.com have the tools they need to automate identity and access management. Our first public launch is a SAML-based Single Sign-on (SSO) option. Administrators will have the ability to manage their GitHub users through the identity provider that already manages access to the host of applications they use in their current workflow. This option isn’t ready quite yet, but it will launch as a beta in the coming months. Sign up to try it out when it does.

Get help from the GitHub Community

We’re grateful to have a community of more than 16 million developers. While developers gain experience implicitly on GitHub as they work alongside other developers, we know that’s not enough. To help, we’re creating a dedicated space for you to learn from each other—and to have conversations about GitHub itself.

The GitHub Community Forum will become a place where developers can talk shop, get help, and learn together. It will also help us introduce new features and improvements and give developers the ability to share thoughts and feedback with us directly. Look out for the GitHub Community Forum in 2017.

See what’s behind your green squares

New user profiles

Your profile now contains your entire history of work on GitHub, from your first commit to your most recent pull request. And a per-repository breakdown reveals where you're spending your time each month. You can see special events in your history—the day you signed up for GitHub, opened your first pull request, or joined an organization—and showcase your best work by pinning favorite projects to your profile. For more on what’s changed, take a look at the documentation or watch the video.

While I’m really excited about these improvements to GitHub, I’m more excited to see what you’ll create with them.

Are you new around here? Introducing an on-demand course in GitHub basics

If you'd like to start using GitHub or just see what it's all about, we're kicking off a new way for you to learn the basics. Introduction to GitHub is a self-paced, online class designed to help you:

  • Get started using GitHub.com in 30 minutes or less.
  • Make new friends while collaborating on a fun project.
  • Dive into the worlds of GitHub and open source.

Unlike many self-paced training classes where you are completely alone, this one has a thriving Gitter community where GitHub Trainers drop in several times a day to answer questions and help those who are stuck. During the course, you are encouraged to complete an activity where you will drop a pin on our map representing your current location. Check out our current pins here to see where people are learning.

This course is 100 percent free forever and uses several popular open source projects to create a seamless learning experience. Here are a few of the projects we would like to thank:

Even if you've been using GitHub for a while, we hope you will try out the course and share your feedback in the class survey. If you think it's a good introduction to GitHub, we hope you will share the class) with others who'd like to learn.

Improving collaboration with forks

If you've ever wanted to make minor changes before merging a pull request, now you can. When a user opens a pull request from a fork, they'll be given a new option that allows the upstream repository contributors to collaborate with them on their new branch.

allow collaboration

Simply clone the contributor's fork and, if you've been granted permission, you'll be able to push changes to the head branch on the open pull request, even if you don't normally have permission to push to the fork.

Pull requests created before the option was available will default to not allowing collaboration, but contributors can also enable or revoke permission, by using the new checkbox in the pull request sidebar.

allow-maintainers-to-make-edits-sidebar-checkbox

Learn more about collaborating with forks in our help guide.

GitHub Pages now runs Jekyll 3.2

As promised, GitHub Pages has been upgraded to Jekyll 3.2. The move to Jekyll 3.2 brings over 100 improvements including the introduction of Gem-based themes.

You can begin using the Minima theme, starting today, by adding theme: minima to your site's config, a move which eliminates the need to manually copy templates or stylesheets into your repo. While Minima is the only theme supported today, we're working to make more themes available for use on GitHub Pages. Check out the GitHub help documentation for more information on adding a theme to your GitHub Pages site.

This should be a seamless transition for all GitHub Pages users, but if you have a particularly complex Jekyll site, we encourage you to get in touch with us. For more information on these changes, see the Jekyll changelog.

See the users you've blocked on your settings page

You've been able to block users for a while now, but you can now see who you've blocked from your account settings page. You can also search and add new users to your blocked list, as well as unblock any user that you've blocked by accident.

block-users

Of course, if a user is bothering you, you can always block them from their profile page directly.

block-users-profile

Check out the GitHub Help documentation for more information about blocking a user from your personal account or how to block a user from your organization.

Simpler GitHub Pages publishing

We're making it easier to publish a website with GitHub Pages. Now you can select a source in your repository settings and GitHub Pages will look for your content there.

Screenshot of Repository Settings - GitHub Pages - Source

  1. Selecting master branch will publish your site from the master branch. This is useful for repositories dedicated to website content.
  2. Selecting master branch /docs folder will publish from the /docs folder of your master branch. This lets you maintain documentation and code together on one branch, and open source maintainers can accept contributions for both in a single pull request.

Rest assured that existing project pages which use a gh-pages branch will keep working just like before, as will user and organization pages published from the master branch.

Check out the documentation to learn more.