Simple repository/folder-structure to be used as base when crating new GitHub repositories.
As time goes by, the more I use GitHub. Due to this, I felt the need to create a simple boilerplate for my repositories on GitHub.
The purpose is to unify my repositories, using a folder structure, files and conventions that I find appropriate.
All github recommended community standards files should be within .github folder, except the LICENSE.txt file (this one should be in the root). Those files are:
- README.md
- CONTRIBUTING.md
- ISSUE_TEMPLATE.md
- PULL_REQUEST_TEMPLATE.md
Also, for simplicity, there's two more files to help to write down simple tasks and register minor updates:
- TODO.md
- CHANGELOG.md
GitHub automatically search for those markdown files in the root folder, .github folder and the docs folder. For organization purposes, the docs folder will be used to keep documentation about the project.
The headers are mostly used in the README.md file and, to provide a better structure, there's some conventions I use:
| Header | How it's done |
|---|---|
| The repository name (title) should always be a h1 written with underline-ish style. | 'repo-name' |
| The sections should follow the same rule, but must be a h2 header. | 'section-name' |
| The subsections headers starts at h3 and should never be as big as the title or the sections. | ### 'subsection-name' |
| Between the title and every section, there will be a horizontal rule to emphasize the division. | --- |
For every project, the README.md file must have at least the following basic headers structure:
Repository-name (title) ====== --- Getting Started ------ Installation and Usage ------ ### Pre requisites ### Running --- License ------
All the documentation should be inside /docs, and can be done with .md or .html files. Since GitHub-page is a powerfull resource and any repository can have a web page, the documentation is usually done with .html files using the Skeleton Boilerplate, and the repo link is placed in the description of the repository.
The main folder structure should be the same as this repository:
.
├── LICENSE.txt
├── .github
│ ├── README.md
│ ├── CONTRIBUTING.md
│ ├── ISSUE_TEMPLATE.md
│ ├── PULL_REQUEST_TEMPLATE.md
│ ├── TODO.md
│ └── CHANGELOG.md
├── docs
│ ├── index.html
│ └── assets
│ ├── css
│ ├── js
│ └── images
└── src
└── ALL SOURCE FILES GOES HERE
In need of more folders to organize the repo, do as you wish, but at least preserve this structure.