Translator: qhxin

The original link

Publishing a website or software document on GitHub Pages now requires fewer steps — three, to be exact:

  1. Create a GitHub repository (or select one that is already created);

  2. Submit a Markdown file through the GitHub web page like you would submit any other file;

  3. Activate GitHub Pages in your repository Settings.

Just like that — you now have a website. If you’re already familiar with GitHub Pages, you might be interested to know a little bit about what’s going on behind the scenes. We’re working on a few things to simplify the publishing process and make it much easier for you to create Markdown content elsewhere on GitHub.

  1. All Markdown files are now rendered by GitHub Pages, freeing you from the need to add YAML predescriptions (metadata separated by — symbols at the top of the file) to each file.

  2. If you don’t have a file named index.md (or index.html), we’ll use your README file as the front page of the site, just like you’d see browsing a repository on GitHub.

  3. If you don’t specify a theme in your site profile (or if you don’t have one at all), we’ll set a minimal default theme that matches the look and feel of other Markdown files on GitHub.

  4. If a given file does not explicitly specify which layout to use, we will specify one based on its context. For example, a page will automatically become a Page layout, and if the page layout does not exist, it will become a default layout.

  5. If your page does not have a clear title and the file starts with an H1, H2 or H3 tag, we will use the tag content as the page title and display it in the browser TAB.

These improvements should make it faster and easier to publish your first (or hundredth) website in a few clicks, or to document your software projects in the repository by simply adding Markdown files to the /docs directory. Of course, you can still control the look and feel with additional customizations, such as overwriting the default theme with your own layout and styles.

While these changes should not affect the construction of most existing sites, there are two potential pitfalls for early Jekyll users:

  1. If your site traverses all pages (for page in site.pages, for example), you may now find additional pages (such as README pages from third-party libraries) in the list. You can use the exclude configuration in the configuration file to explicitly exclude these files.

  2. If you don’t specify the layout and title of a page and want it to stay that way (for example, if you need to provide unstyled content), you need to explicitly set the values of these configurations to NULL.

If for any reason you don’t want to use these features, you can disable them by adding a.nojekyll file to your site root.

As a result, the GitHub Pages generation process is as transparent and customizable as possible, with all the features mentioned above implemented as Jekyll open source plug-ins, That is, Jekyll Optional Front Matter, Jekyll README Index, Jekyll Default Layout, and Jekyll Titles from keywords these plug-ins.

Again, these changes should not affect the construction of most existing sites (although you can safely start using these features), but if you have any questions, please contact us.

Three steps to release happiness!