How does Github use Github to process Github documentation?

How does Github use Github to process Github documentation?

Providing well-written documents can help people understand and use your project well, and people can easily participate in and contribute to your project, but this is not enough. The underlying system of document service makes it easier for anyone, including you or your team, to write documents.

The biggest difficulty in writing a document is not how to configure the tool, or how to deploy updates, but how to explain the sentence. Members of the GitHub document production team have a rich working background, including using native XML-based writing tools and complex CMS systems. But we don't want to use those tools, so we spend a lot of time and effort configuring our own document production processes and work plans.

We have talked about how to use GitHub to build GitHub. The following is how we use GitHub Pages to provide our GitHub help documentation to millions of readers every month.

Our previous process

A few months ago, we migrated the site that helped the system from the self-built Rails program to Jekyll on Github Pages. Previously, our help system needed two independent project warehouses:

 

• It is responsible for website O & M, website resource management, and Rails Applications that implement document search.

• Website content composed of a large number of Markdown files

Our Rails application is hosted on a third-party platform. As the code continues to be updated and upgraded, we deployed it in Hubotand Chatops, which were all completed in our spare time to maintain the Github main site.
Our normal writing process may look like this:

 

• When new features are developed, the document team first prepares the document content.

• Create a new issue to track this feature

• After the document is updated, we initiate a pull request to iteratively update the document content.

• After the PR is successfully initiated, we will use @ to remind the Team (such as @ github/docs) and ask our teammates to review our content.

• When this feature has been developed and launched, we will merge the previously created PR. Webhook can help us quickly activate our Rails application in the content repository. Webhook is responsible for updating the database.

The following is a simple example. @ neveretand @ bernars shows us our normal workflow:

 

It is interesting to use pull requests for work, because it is exactly the same as the Github workflow used by our team. The Markdown syntax allows us to express the uniqueness of new features quickly and efficiently, so we have a special liking for it when writing documents.

However, it is quite troublesome to maintain our Rails program:

• Because our hosts are hosted externally, we need professional engineers from engineering, O & M, and security teams to monitor the running status of the site in real time and handle emergencies in a timely manner.

• Our document team cannot easily preview content changes. Although we use Markdown to write content, we can preview it in real time, however, we still need to configure a local Rails application service to run the script to import the content to the database and observe its final effect on the website.

• Although we constantly adjust the Rails server settings, the response speed after the user initiates the request is still slow. This is because the HTML page is dynamically generated and requires frequent access to the database. Even if more powerful cache policies are used, the effect is still minimal.

We realized that we could do better.

Our new process

When Jekyll 2.0 was released, we realized it was time to use static websites! In particular, the new collection Document Type feature makes it possible to define your own file structure. In addition, Jekyll 2.0 also supports Sass and CoffeeScript to simplify the preparation of front-end code.

The advantage of open source is that it is open. After we migrated to Jekyll, we also initiated a lot of pull requests to the Jekyll project, contributing Code so that it can better serve the majority of users of Github Pages.

At this time, our workflow has undergone a small change. However, we still use Markdown to submit the written content to the warehouse for others' review. After the submission is merged, the Github Pages website will be automatically created and deployed in a few seconds.

The following is a simple outline of how to use the core features of Jekyll and the plug-in that helps the system improve the effect on Github.

Our magic weapon

We mainly rely on the features of the core code of Jekyll to complete the task, which is more effort-saving than a lot of effort to maintain custom plug-ins.

The new Converter plug-in provided by Jekyll 2.0 can automatically convert any tag into HTML. In this way, users can write articles freely. Jekyll is only responsible for running the final HTML file. For example, you can use the AsciiDoc syntax to publish a post.

Finally, we developed the jekyll-html-pipeline plug-in, which is an enhanced version of our open-source html-pipeline on Jekyll. This ensures that the content of our help site remains unchanged throughout Github. At the same time, we also use our own Markdown filter plug-in to provide some syntax extensions, further reducing the difficulty of document writing.

Search

On the previous Rails site, we used the ElasticSearch provider to index our database and implemented a search system for our help site.

Now, we use lunr-js to provide a faster client search experience. Through our analysis and screening, we found that the vast majority of users rely on external search service providers to obtain our documents. It makes no sense to spend a lot of effort on the server's search solution during or after the migration.

Content reference

The document team wants to use "content reference" When writing the document ". Through content reference, you can write a large text segment and reuse it anywhere on the website. (This idea is based on the DITA standard)

The old Rails application does not allow us to write reusable content, but now we are leveraging the power of Jekyll data files. We have created a particle calledConrefs. ymlAnd write a series of key-value set strings as follows:

Repositories:
Create_new:
1. In the upper-right corner of any page, click {octicon-plus Plus symbol}, and then click ** New repository **.
! [New repository menu] (/assets/images/help/repository/repo-create.png)

Our keys are grouped according to (repositories. create_new) species. the corresponding value is the following Markdown source code ("In the upper-right corner ..."). To use the appropriate syntax, you only need to create a new repository on different page references in a simple step.

To start the process:
 
{Site. data. conrefs. repositories. create_new }}
2. Do something else.
3. You're done!

As the Github interface changes, we may need to modify the image or redefine the direction. In this way, we only need to use content reference to change one place rather than many places.

Versionized document

Another benefit of this change is the ability to provide a version-based help document. With the release of Github enterprise 2.0, we began to provide different help document content for the previous versions 11.10.340 and 2.0. To achieve this, we used a special flag audience on the Jekyll site and checked this flag when generating HTML in the Pages repository.

For example, in our config. yml file, we set a key named audience whose value is 11.10.340. If a feature exists in enterprise 2.0 and is not in 11.10.340, we use the following syntax to mark this part:

{% If site. audience! = '11. 10.340 '%}
 
This new feature...
 
{% Endif %}

The preceding implementation only utilizes the core features of Jekyll, and we do not need to create or maintain anything else.

Test our site

This is not because the site is static. We can avoid development and testing drivers.

Our first test content tool has always been html-proofer. This tool quickly checks every URL on our site to help us verify that our links and images are normal.

Ruby users are more familiar with simulating website interactions using capyloud in their tests. Is this idea crazy about implementing a similar tool in our static website? No! Our engineer @ bkeepers wrote a blog about this issue four years ago. In this way, we have the ability to perform a stronger test that covers our content and website behavior. For example, we check whether the key in the YAML file exists to check whether a content is valid or whether the javascript code is running well.

Our help documentation runs on CI to ensure that users do not get corrupted content:

Fast

As mentioned above, compared with the original Rails application, our new Pages implementation greatly improves the speed. This is partly because the website content is mainly a large number of static HTML files-no need to access the database. But most importantly, we spent a lot of time optimizing the Pages Server to speed up access. In addition, we can also meet the service conditions such as CDN.

Let Github Pages work for you

The document team on Github can use the Github workflow, Jekyll 2.0, and Github Pages to create high-quality documents. The benefits provided by Github Pages to our document team also apply to any users who use Github Pages.

As we migrate documents to Pages, we no longer need to recreate any new components. It takes us a little time to create something and spend a lot of time discussing what kind of workflow is meaningful to our team and company. By hosting systems like Github users, we can provide better and faster document systems. Our internal workflows greatly improve our work efficiency and provide some features that we have never provided before, such as versionized documents.

If you have any questions about our process, we will be happy to help you at any time.

GitHub Tutorials:

GitHub tutorials

Git tag management details

Git branch management

Git remote repository details

Git local Repository (Repository) Details

Git server setup and Client installation

Git Overview

Share practical GitHub tutorials

GitHub details: click here
GitHub: click here

How GitHub uses GitHub to document GitHub

This article permanently updates the link address: