sleepred / asciidoc-readme-template Goto Github PK

• 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.

Select the prequisites procedure which aligns with your operating system of choice.

This repository is published as a template repository, hosted on GitHub. The branches within this repository include a boilerplate README, as well as a placeholder README, for your convenience. To ensure you repository includes these convenience branches, you’ll need create your repository from within the GitHub website.

1. On GitHub, navigate to the main page of this repository.

2. Above the file list, click Use this template.

   

3. Use the Owner drop-down menu, and select the account you want to own the repository.

   

4. Type a name for your repository, and an optional description.

   

5. Choose a repository visibility. For more information, see About repository visibility.

   

6. To include the directory structure and files from all branches in the template, YOU MUST select Include all branches.

   

7. Click Create repository from template.

8. On GitHub, navigate to the main page of the repository.

9. Above the list of files, click Code.

   

10. To clone the repository using HTTPS, under "Clone with HTTPS", click to copy the URL.

    

11. Launch your terminal.

12. Change the current working directory to the location where you want the cloned directory.

13. Type `git clone `, and then paste the URL you copied earlier

    git clone https://github.com/YOUR-USERNAME/YOUR-REPOSITORY

14. Press Enter to create your local clone.

    git clone https://github.com/YOUR-USERNAME/YOUR-REPOSITORY
    > Cloning into `Spoon-Knife`...
    > remote: Counting objects: 10, done.
    > remote: Compressing objects: 100% (8/8), done.
    > remove: Total 10 (delta 1), reused 10 (delta 1)
    > Unpacking objects: 100% (10/10), done.

1. Launch your terminal.

2. Change the current working directory to the location where you already cloned the repository.

3. Copy & paste the following into the terminal window and hit Return.

   git checkout docs/readme-placeholder
   git checkout main
   git rm readme.adoc
   git clean -f .
   git commit -m 'DOCS(readme):  purge boilerplate'
   git merge docs/readme-placeholder -m 'DOCS(readme):  stage placeholder' --allow-unrelated-histories

4. You can now edit the readme.adoc file to serve as a placeholder until the actual readme is ready to be published.

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

   💡	The example listed above is only a starting point for customizing 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 when displaying on GitHub.

5. Once your edits are complete, commit your changes and push to remote.

   git add .
   git commit -m 'DOCS(readme):  set placeholder'
   git push

1. Launch your terminal.

2. Change the current working directory to the location where you already cloned the repository.

3. Copy & paste the following into the terminal window and hit Return.

   git checkout docs/readme-boilerplate
   git checkout -b docs/readme-draft

4. You can now edit the readme.adoc file, customizing it for your specific project.

5. Once the readme is ready to be published, copy & paste the following into the terminal window and hit Return.

   git add .
   git commit -m 'DOCS(readme):  author draft'
   git push -u origin docs/readme-draft
   git checkout main
   git rm readme.adoc
   git clean -f .
   git commit -m 'DOCS(readme):  purge placeholder'
   git merge docs/readme-draft -m 'DOCS(readme):  publish draft' --allow-unrelated-histories
   git push

For more AsciiDoc examples, please refer to the Documentation.