Getting Started¶

Follow these steps to quickly set up and start working on this project:

1. Fork the Repository:

2. Begin by forking this repository to your GitHub account.

3. Clone the Repository:

4. Clone your forked repository to your local machine:

   git clone https://github.com/YOUR_USERNAME/docs-templates.git
   cd docs-templates
   

5. Configure GitHub Pages:

6. In your docs-templates repository settings, go to Actions -> Pages.
7. Set the Build and Deployment source to Deploy from a branch.
8. Choose the gh-pages branch and set the folder to /(root).

9. Save your changes.

   

10. Configure Gist:

11. In the repository's About section, click the Settings gear icon.

    

12. Enable the Use your GitHub Pages Website option and Save the changes.

    

13. Customize Markdown Files:

14. The actions and pages in this template are set up to build your gist based on the structure defined in mkdocs.yml under the nav section.

    nav:
      - Home:
          - page-0.md
      - Section 1:
          - page-1.md
      - Section 2:
          - page-2.md
    

15. The nav section is where you define the structure of your documentation site. You can create nested pages to organize your content into sections and subsections, providing a clear hierarchy for users to navigate. For example, to add nested subsections within a section, your nav might look like this:

    nav:
      - Home: index.md
      - Section 1: page-1.md
      - Section 2: page-2.md
      - Section 3:
          - Overview: section-3/overview.md
          - Details:
              - Subsection 1: section-3/details/subsection-1.md
              - Subsection 2: section-3/details/subsection-2.md
    

16. In this example:

    • Section 3 contains an Overview page and a Details section with two subsections.
    • Each entry under nav corresponds to a markdown file that you have created in the docs/ directory.
    • You can rename sections, subsections, and pages as needed to match your documentation structure.

17. Rename sections and corresponding markdown files as needed. Ensure the nav entries in mkdocs.yml match your markdown file names.

18. After editing or adding markdown files, commit and push your changes:

    git add .
    git commit -m "<describe your changes>"
    git push origin main
    

19. Rename sections and corresponding markdown files as needed. Ensure the nav entries in mkdocs.yml match your markdown file names.

20. Navigate to your Gist and see your finished product!