README Template AsciiDoc

A README template written in AsciiDoc markup
Explore the docs »

Table of Contents

• Purpose
  • Built With
• Getting Started
  • Prerequisites
  • Clone This Repository
• Usage
  • Create a Branch For Your README Draft
  • Display a README Placeholder on GitHub
  • Publish Your README Draft
• FAQ
• Roadmap
• Contributing
• Change Log
• License
• Contact
• Acknowledgements

Purpose

This template is offered to help create new repositories and kickstart your documentation process. It includes boilerplate text for a well-structured README. As a convenience, it also includes a placeholder README for what visitors to your repository will see while work is still in progess. See the placeholder screenshot below.

Why? Why another README template when so many README templates already exist? This README is written in AsciiDoc markup, instead of Markdown. The syntax is very similar to markdown and easy to learn. Documents written in AsciiDoc markup are more easily converted to HTML5, PDF, EPUB, and other formats.

Asciidoc is a more powerful markup language designed for more complex content. Asciidoc uses a more extensive syntax than Markdown, allowing you to create more advanced formatting elements such as tables, footnotes, and cross-references. All without the headaches of inconsistent implementations frequently found with Markdown. For writing high-quality documentation, it just works.

AsciiDoc is simply plain-text. You can author documents in your favorite text editor of choice, such as Visual Studio Code with a proper extension, or any derivative of VIM (Neovim, VimR). If you’re just getting started with AsciiDoc, you may want to try AsciidocFX, until the markup syntax becomes second nature to you. The choice is yours.

Built With

• Asciidoctor - a fast text processor and publishing toolchain for converting AsciiDoc content to other formats.

• AsciidocFX - a book / document editor to build PDF, Epub, Mobi and HTML books, documents, and slides.

Getting Started

Follow these procedures to set up a local repository for your project.

Prerequisites

These procedures utilize the GitHub CLI and assume you are hosting your repository on GitHub. Select the procedure which matches your operating system.

Installing GitHub CLI on macOS

ℹ️	This assumes the Homebrew package manager is already installed.

Copy & paste the following into the terminal window and press Return.

brew install gh

You may now proceed to Clone This Repository.

Installing GitHub CLI on Windows

You may open either a Command Prompt, PowerShell, or Windows Terminal.

Copy & paste the following into the PowerShell window and press Return.

winget install --id GitHub.cli

You may now proceed to Clone This Repository.

Installing GitHub CLI on Linux

The GitHub CLI is available for a variety of Linux distributions.
===== Debian, Ubuntu Linux, Raspberry Pi OS (APT)
Open a terminal window. Copy & paste the following into the terminal window and press Return. You may be prompted to enter your password.

sudo apt update
sudo apt install gh -y

Fedora, CentOS, Red Hat Enterprise Linux (dnf)

Open a terminal. Copy & paste the following into the terminal window and hit Return. You may be prompted to enter your password.

sudo dnf install gh

You may now proceed to Clone This Repository.

Clone This Repository

This repository is available on GitHub as a template repository. As a convenience, the branches within this repository include a boilerplate README, as well as a placeholder README. To ensure your repository includes these branches, you’ll need to create your repository using the GitHub CLI. The following procedure will clone and create a local copy of this repository.

1. Launch your terminal.

2. Change Working Directory:
   Change your working directory to the location where you want to create the local repository. Use the cd command and replace WORKING_DIRECTORY with the path to the directory of your choice:

   cd WORKING_DIRECTORY

3. Authenticate with GitHub:
   If you haven’t already authenticated with GitHub CLI, run the following command and follow the prompts:

   gh auth login

4. Create a Local Clone from a Template Repository:
   Use the gh rep create command with the --template option to create a clone of a template repository. Use the --clone option to create a local clone. Use the --public option to make the new repostory public, or use the --internal or --private options instead. Use the --include-all-branches option to include all branches from the template repository. Replace NEW_REPO_NAME with a name of your choice. Replace TEMPLATE_OWNER with the template repository owner’s username or organization, and TEMPLATE_REPO with the template repository name:

   gh repo create --clone --public --include-all-branches MY_NEW_REPO --template TEMPLATE_OWNER/TEMPLATE_REPO

   For example:

   gh repo create --clone --public --include-all-branches my-new-repo --template JoeArauzo/AsciiDoc-README-Template

   You should see output similar to the following:

   Created repository YOUR_USERNAME/my-new-repo on GitHub
   Cloning into 'my-new-repo'

5. Navigate to the Local Repository:
   Change your working directory to the newly created local repository:

   cd NEW_REPO_NAME

Usage

The following instructions are provided as a way to get started with setting up your new repository.

ℹ️	This assumes git is already installed and configured on your system.

Create a Branch For Your README Draft

Your new repository includes the boilerplate text you’re reading here. Create a branch so you can use this text as a starting point for authoring your own README.

1. Create a Branch:
   Continuing from your local repository, use the git checkout command with the -b option to create and switch to the new branch in one step. Replace NEW_BRANCH_NAME with the name of your choice:

   git checkout -b NEW_BRANCH_NAME

   For example:

   git checkout -b docs/readme-draft

2. Push the New Branch to Remote:
   Push the new branch to the remote repository (e.g., GitHub), using the following command:

   git push origin docs/readme-draft

Now you can proceed to personalize this README for your own needs. Additional instructions will be provided below to get your personalized README to show up on GitHub. Unitl ready, a placeholder README can be used.

Display a README Placeholder on GitHub

A README placehholder can be displayed on GitHub until your own README is ready. The use of a placholder is a good practice, by providing visitors with a hint of what’s in store. This template includes a branch with a placholder you can personalize for your own needs.

1. Checkout the README Placeholder branch:
   Use the git checkout command to switch to the branch with the placholder README.

   git checkout docs/readme-placeholder

2. Personalize the README Placeholder:
   Modify the README placeholder by editing the file and with your preferred metadata, title, description and optional link.

   = <Enter the Project Title>
   :doctype: article
   :description: <Enter a short description of the project>
   :license-type: <enter license type>
   :author: Author Name
   :email: author.name@domain.com
   :revnumber: v0.1
   :revdate: 2021-01-01

   💡

   The example listed above is only a starting point for personalizing the README. Take a close look at the lines within to ensure you replace all the placeholder values. For example, don’t forget to modify the HTML code near the top of the README which is used to work around a display issue on GitHub.

3. Commit Changes:
   You now have changes in the README placeholder that you must commit before proceeding.

   git commit -am "docs(readme): personalize placeholder"

4. Push the Placeholder Branch to Remote:
   Push the changes to the remote repository (e.g., GitHub), using:

   git push origin docs/readme-placeholder

5. Merge Placeholder into Main Branch:
   To display the README placeholder on GitHub, you must merge the placeholder branch into the main branch. Use the the following commands:

   git checkout main
   rm readme.adoc
   git rm readme.adoc
   git commit -am "docs(readme): purge readme"
   git merge docs/readme-placeholder -m "docs(readme): merge branch 'docs/readme-placeholder'" --allow-unrelated-histories

6. Push the Changes:
   Push the changes so they show up in GitHub.

   git push

   Your personalized README placeholder is now displayed on GitHub.

Publish Your README Draft

After you’ve displayed the README placeholder on GitHub, you can resume work on your README on the docs/readme-draft branch. Follow these steps.

1. Checkout the README Draft branch:
   Use the git checkout command to switch to the branch with the README draft.

   git checkout docs/readme-draft

2. Personalize your README Draft:
   Make whatever changes you want to the readme.adoc file, then commit those changes.

   git commit -am "docs(readme): personalize draft"

3. Merge README Draft into Main Branch:
   Use the following commands:

   git checkout main
   rm readme.adoc
   git rm readme.adoc
   git commit -am "docs(readme): purge readme"
   git merge docs/readme-draft -m "docs(readme): merge branch 'docs/readme-draft'" --allow-unrelated-histories

4. Push the Changes:
   Push the changes so they show up in GitHub.

   git push

   Your README draft is now merged into the main branch and displayed on GitHub.

For more AsciiDoc examples, please refer to the Documentation.

FAQ

1. Why this approach?

   Because…​

2. Could this be done better?

   Certainly…​

Roadmap

See the open issues for a list of proposed features (and known issues).

Contributing

1. Clone repo and create a new branch: $ git checkout https://github.com/JoeArauzo/AsciiDoc-README-Template -b name_for_new_branch.

2. Make changes and test.

3. Submit Pull Request with comprehensive description of changes.

Change Log

See CHANGELOG.

License

Distributed under the MIT License. See LICENSE for more information.

Contact

Author Name - author.name@domain.com

Project Link: https://github.com/JoeArauzo/AsciiDoc-README-Template

Acknowledgements