Top Related Projects
The source code that powers readthedocs.org
Project documentation with Markdown.
🃏 A magical documentation site generator.
Easy to maintain open source documentation websites.
The Sphinx documentation generator
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
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.
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.
🃏 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.
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.
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 CopilotREADME
GitHub Docs
Welcome to GitHub Docs! GitHubâs documentation is open source, meaning anyone from inside or outside the company can contribute. For full contributing guidelines, visit our contributing guide
Quick links by contributor type
-
Hubbers (GitHub employees): See CONTRIBUTING.md in the
docs-contentrepository for GitHub-specific processes. -
Open source contributors: See CONTRIBUTING.md in the
docsrepository for a quick-start summary.
How we sync changes across Docs repositories
There are two GitHub Docs repositories:
-
github/docs(public): Open to external contributions -
github/docs-internal(private): For GitHub employee contributions.
The two repositories sync frequently. Content changes in one are reflected in the other. Hubbers might prefer to post in docs when working with a customer, but docs has limitations on the types of contributions it accepts to safeguard the site and our workflows. Internal contributions should usually go to docs-internal.
Important: The docs repository accepts contributions to content files (.md files in /content and select /data sections like reusables only). Infrastructure files, workflows, and site-building code are not open for external modification.
New to contributing
Here are some resources to help you get started with open source contributions:
- Finding ways to contribute to open source on GitHub
- Set up Git
- GitHub flow
- Collaborating with pull requests
License
This project is dual-licensed under:
- Creative Commons Attribution 4.0 - for documentation and content in the assets, content, and data folders (see LICENSE)
- MIT License - for code (see LICENSE-CODE)
Top Related Projects
The source code that powers readthedocs.org
Project documentation with Markdown.
🃏 A magical documentation site generator.
Easy to maintain open source documentation websites.
The Sphinx documentation generator
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