docs

The open-source repo for docs.github.com

16,067

59,181

16,067

View on GitHub

Top Related Projects

readthedocs.org

7,982

The source code that powers readthedocs.org

mkdocs

19,012

Project documentation with Markdown.

docsify

27,355

🃏 A magical documentation site generator.

docusaurus

55,406

Easy to maintain open source documentation websites.

Quick Overview

The GitHub docs repository is the official documentation for the GitHub platform, providing comprehensive information on using GitHub, its features, and various GitHub-related tools and services. It serves as a central hub for developers, contributors, and users to learn about and navigate the GitHub ecosystem.

Pros

Comprehensive Documentation: The repository covers a wide range of topics, from basic GitHub usage to advanced features and integrations, making it a valuable resource for users of all skill levels.
Community Contribution: The documentation is open-source, allowing the community to contribute, improve, and maintain the content, ensuring it stays up-to-date and relevant.
Multilingual Support: The documentation is available in multiple languages, catering to a global audience and making it more accessible.
Continuous Improvement: The repository is actively maintained, with regular updates and improvements to the documentation based on user feedback and evolving platform features.

Cons

Complexity: The breadth of content and the depth of information can sometimes make it challenging for new users to navigate and find the specific information they need.
Potential Inconsistencies: With multiple contributors, there may be occasional inconsistencies in the writing style, formatting, or level of detail across different sections of the documentation.
Outdated Information: While the team works hard to keep the documentation up-to-date, there may be instances where information becomes outdated due to the rapid pace of changes in the GitHub platform.
Limited Offline Access: The documentation is primarily web-based, which may pose challenges for users who need to access it in offline or low-connectivity environments.

Getting Started

To get started with the GitHub docs repository, follow these steps:

Visit the official GitHub docs website at https://docs.github.com.
Explore the main navigation menu to find the section or topic you're interested in, such as "Guides", "Reference", or "Contributions".
Browse the available articles and documentation pages to find the information you need.
If you're a contributor, you can navigate to the github/docs repository on GitHub to view the source files and contribute to the documentation.
To contribute, you can follow the guidelines outlined in the CONTRIBUTING.md file, which provides instructions on how to submit issues, create pull requests, and collaborate with the community.

Competitor Comparisons

readthedocs.org

7,982

The source code that powers readthedocs.org

Pros of readthedocs.org

Open-source platform for hosting documentation
Supports multiple programming languages and frameworks
Offers versioning and localization features

Cons of readthedocs.org

Limited customization options compared to docs
May require more setup and configuration
Less integrated with GitHub ecosystem

Code Comparison

readthedocs.org:

from readthedocs.projects.models import Project

def build_docs(project_slug):
    project = Project.objects.get(slug=project_slug)
    project.build_docs()

docs:

import { getDocsBranch } from '../lib/git-utils'

async function getDocsVersion() {
  const branch = await getDocsBranch()
  return branch === 'main' ? 'free-pro-team@latest' : branch
}

The code snippets showcase different approaches:

readthedocs.org uses Django models for project management
docs utilizes JavaScript and Git-related utilities for version handling

Both repositories focus on documentation, but readthedocs.org is a platform for hosting various projects' docs, while docs is specifically for GitHub's own documentation. readthedocs.org offers more flexibility for different projects, while docs is more tightly integrated with GitHub's ecosystem.

mkdocs

19,012

Project documentation with Markdown.

Pros of MkDocs

Lightweight and easy to set up for small to medium-sized documentation projects
Supports themes and plugins for customization and extended functionality
Built-in search functionality without additional configuration

Cons of MkDocs

Less suitable for large-scale documentation projects with complex structures
Limited built-in features compared to more comprehensive documentation platforms
Requires manual deployment and hosting setup

Code Comparison

MkDocs configuration (mkdocs.yml):

site_name: My Docs
theme: material
plugins:
  - search
nav:
  - Home: index.md
  - About: about.md

Docs configuration (docs/index.yml):

version: 1
name: GitHub Docs
shortName: Docs
productLogoPath: assets/images/site/logo.png
featuredLinks:
  gettingStarted:
    - /get-started/quickstart/hello-world

Both repositories serve different purposes: MkDocs is a general-purpose documentation generator, while Docs is specifically tailored for GitHub's documentation. MkDocs offers simplicity and flexibility for various projects, whereas Docs provides a more comprehensive solution for GitHub-specific documentation needs.

docsify

27,355

🃏 A magical documentation site generator.

Pros of Docsify

Lightweight and easy to set up with minimal configuration
No build process required, generates pages on-the-fly
Supports plugins for extended functionality

Cons of Docsify

Limited built-in features compared to Docs' comprehensive documentation system
Less integrated with GitHub ecosystem and workflows
May require more manual maintenance for large-scale documentation projects

Code Comparison

Docsify configuration (index.html):

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>My Documentation</title>
</head>
<body>
  <div id="app"></div>
  <script>
    window.$docsify = {
      name: 'My Docs',
      repo: 'https://github.com/username/repo'
    }
  </script>
  <script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
</body>
</html>

Docs configuration (config.yml):

title: GitHub Docs
description: Help documentation for GitHub.com
versions:
  - free-pro-team@latest
  - enterprise-server@3.0
  - enterprise-server@2.22
  - enterprise-server@2.21

Both repositories serve different purposes: Docsify is a documentation site generator, while Docs is GitHub's official documentation. Docsify offers simplicity and flexibility for smaller projects, whereas Docs provides a robust, feature-rich system tailored for GitHub's extensive documentation needs.

docusaurus

55,406

Easy to maintain open source documentation websites.

Pros of Docusaurus

Easier to set up and customize for non-technical users
Built-in support for versioning documentation
More flexible theming and plugin system

Cons of Docusaurus

Less integrated with GitHub ecosystem and features
May require more configuration for complex documentation structures
Limited built-in search capabilities compared to GitHub's powerful search

Code Comparison

Docusaurus configuration (docusaurus.config.js):

module.exports = {
  title: 'My Project',
  tagline: 'Documentation made easy',
  url: 'https://myproject.com',
  baseUrl: '/',
  onBrokenLinks: 'throw',
  onBrokenMarkdownLinks: 'warn',
  favicon: 'img/favicon.ico',
  organizationName: 'myorg',
  projectName: 'myproject',
};

GitHub Docs configuration (config.yml):

title: GitHub Docs
description: Help documentation for GitHub.com and GitHub Enterprise
versions:
  fpt: '*'
  ghes: '*'
  ghae: '*'
  ghec: '*'
languages:
  - en
  - es
  - ja
  - pt

Both repositories use different approaches to configuration, with Docusaurus using JavaScript and GitHub Docs using YAML. Docusaurus configuration focuses on project-specific settings, while GitHub Docs configuration emphasizes version control and multilingual support.

sphinx

6,394

The Sphinx documentation generator

Pros of Sphinx

More flexible and customizable documentation system
Supports multiple output formats (HTML, PDF, ePub)
Extensive ecosystem of extensions and themes

Cons of Sphinx

Steeper learning curve, especially for non-technical users
Requires more setup and configuration
Less seamless integration with GitHub-specific features

Code Comparison

Sphinx (reStructuredText):

.. code-block:: python

   def hello_world():
       print("Hello, World!")

.. note::
   This is a sample function.

Docs (Markdown):

```python
def hello_world():
    print("Hello, World!")

[!NOTE] This is a sample function.


Sphinx uses reStructuredText by default, which offers more advanced formatting options but can be more complex. Docs uses GitHub Flavored Markdown, which is simpler and more widely adopted in the GitHub ecosystem.

Sphinx provides more control over documentation structure and cross-referencing, while Docs offers a more streamlined approach tailored for GitHub projects. Sphinx is better suited for complex documentation needs, whereas Docs excels in simplicity and GitHub integration.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

GitHub Docs

This repository contains the documentation website code and Markdown source files for docs.github.com.

GitHub's Docs team works on pre-production content in a private repo that regularly syncs with this public repo.

Use the table of contents icon on the top right corner of this document to navigate to a specific section quickly.

Contributing

We accept different types of contributions, including some that don't require you to write a single line of code. For detailed instructions on how to get started with our project, see "About contributing to GitHub Docs."

Ways to contribute

On the GitHub Docs site, you can contribute by clicking the Make a contribution button at the bottom of the page to open a pull request for quick fixes like typos, updates, or link fixes.

You can also contribute by creating a local environment or opening a Codespace. For more information, see "Setting up your environment to work on GitHub Docs."

For more complex contributions, please open an issue using the most appropriate issue template to describe the changes you'd like to see.

If you're looking for a way to contribute, you can scan through our help wanted board to find open issues already approved for work.

And that's it!

If you're having trouble with your GitHub account, contact Support.

That's how you can easily become a member of the GitHub Docs community. :sparkles:

READMEs

In addition to the README you're reading right now, this repo includes other READMEs that describe the purpose of each subdirectory in more detail:

License

The GitHub product documentation in the assets, content, and data folders are licensed under a CC-BY license.

All other code in this repository is licensed under the MIT license.

When using the GitHub logos, be sure to follow the GitHub logo guidelines.

Thanks :purple_heart:

Thanks for all your contributions and efforts towards improving the GitHub documentation. We thank you for being part of our :sparkles: community :sparkles:!

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot