Skip to content

Commit 47d7ed0

Browse files
HarshKapadia2HarshKapadia2
committed
✨ feat: Add content and modify template
1 parent 72b04ba commit 47d7ed0

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

71 files changed

+1376
-290
lines changed

‎CHANGELOG.md

-87
This file was deleted.

‎CONTRIBUTING.md

+129-21
Original file line numberDiff line numberDiff line change
@@ -1,40 +1,148 @@
1-
# Contributing to _Asciidoctor Jet_
1+
# Contributing to Git Internals
22

3-
- Please check the [issues tab](https://github.com/HarshKapadia2/asciidoctor-jet/issues) for things to work on.
4-
- Please [raise an issue](https://github.com/HarshKapadia2/asciidoctor-jet/issues) to request a feature/modification or for reporting a bug, if it has not already been raised.
3+
- Please be mindful of the [Code of Conduct](CODE_OF_CONDUCT.md) while interacting or contributing!
4+
- Please check the [issues tab](https://github.com/HarshKapadia2/git_internals/issues) for things to work on.
5+
- Please [raise an issue](https://github.com/HarshKapadia2/git_internals/issues) to request a feature/modification or for reporting a mistake/bug, if it has not already been raised.
56

67
## Tech Stack
78

8-
- Front end: Asciidoctor, HTML, CSS, JS
9+
- Front end: [Asciidoctor Jet](https://harshkapadia2.github.io/asciidoctor-jet)
910
- CI/CD: GitHub Actions
1011

12+
> NOTE:
13+
>
14+
> - This project uses a Static Site Generator called [Asciidoctor](https://asciidoctor.org).
15+
> - This project is a [PWA](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps).
16+
> - GitHub Actions has been set up on this repo, so a built web site does not have to be committed.
17+
1118
## Local Setup
1219

1320
- Fork this repo. (Top right corner.)
14-
- Clone the forked repo using the [`git clone` command](https://harshkapadia2.github.io/git_basics/#_git_clone).
15-
- `cd` into the cloned repo directory.
16-
- Follow the [Getting Started guide](https://harshkapadia2.github.io/git_basics/#_getting_started) on the demo site and explore other sections to understand how the template is structured.
17-
- Write meaningful commit messages and include the number (#) of the issue being resolved (if any) at the end of the commit message.
21+
- Clone the forked repo using the [`git clone`](https://harshkapadia2.github.io/git_basics/#_git_clone) command.
22+
- [Install Asciidoctor](https://asciidoctor.org/#installation).
23+
- **Please adhere to the [file structure](#file-structure) and [language, code and syntax rules](#language-code-and-syntax) followed in this project.**
24+
- Testing
25+
- Generate the web site in a directory called `build` in the root directory by running the command `sh build.sh` from the root directory.
26+
- It is preferable to use a package like [http-server](https://www.npmjs.com/package/http-server) (`npx http-server "build"`) or [serve](https://www.npmjs.com/package/serve) (`npx serve "build"`) to host the site locally from the `build` directory.
27+
- Please **do not** commit this `build` directory, as the CI process will build the site on merge.
28+
- Make contribution(s)
29+
30+
- Write meaningful commit messages and include the number (`#`) of the issue being resolved (if any) at the end of the commit message.
1831

19-
Example: `:bug: fix: Resolve 'isCorrect' function error (#0)`
32+
Example: `:bug: fix: Resolve 'isCorrect' function error (#0)`
2033

21-
[Commit message format](https://harshkapadia2.github.io/git_basics/#_commit_messagetitle)
34+
[Commit message format](https://harshkapadia2.github.io/git_basics/#_commit_messagetitle)
2235

2336
- Open a Pull Request (PR).
24-
- [Learn how to open a PR.](https://github.com/firstcontributions/first-contributions)
25-
- Solve one issue per PR, without any extra changes.
26-
- Include extra changes in a separate PR.
37+
- [Learn how to open a PR](https://github.com/firstcontributions/first-contributions).
38+
- Solve one issue per PR, **without any extra changes**.
39+
- **Include extra changes in a separate PR.**
40+
41+
## File Structure
42+
43+
### Parsing
44+
45+
Asciidoctor parses files starting from `index.adoc` and follows `include::` to the **relative location** of the next file, to finally get to the file with the content.
46+
47+
**Example**:
48+
49+
This is how the content of [`git-directory.adoc`](https://github.com/HarshKapadia2/git_internals/blob/main/src/content/git-directory.adoc) is displayed:
50+
51+
> Check the raw file contents for the exact syntax.
52+
53+
- In [`index.adoc`](https://github.com/HarshKapadia2/git_internals/blob/main/src/index.adoc):
54+
55+
```asciidoc
56+
include::content/git-directory.adoc[]
57+
```
58+
59+
👇
60+
61+
- In [`content/git-directory.adoc`](https://github.com/HarshKapadia2/git_internals/blob/main/src/content/git-directory.adoc):
62+
63+
```asciidoc
64+
== The `.git` Directory
65+
66+
// Actual content that is displayed
67+
```
68+
69+
### Static Files
70+
71+
- CSS, JS and images are located in the `src/static` directory. Add the appropriate static files to the appropriate directory.
72+
73+
#### Caching
74+
75+
- If any static file is added, please make sure to
76+
- Include it in the `cacheAssets` array in `./src/service_worker.js` as a relative path.
77+
- Increment the value of the `cacheName` variable. (Example: From `v2` to `v3`.)
78+
- Add it to `./src/docinfo.html` with the correct syntax if the static file needs to be linked to the final site.
79+
- If any static file is modified, please make sure to
80+
- Increment the value of the `cacheName` variable. (Example: From `v2` to `v3`.)
81+
- If any static file is deleted, please make sure to
82+
- Remove it from the `cacheAssets` array in `./src/service_worker.js`.
83+
- Increment the value of the `cacheName` variable. (Example: From `v2` to `v3`.)
84+
- Remove it from `./src/docinfo.html` if present.
85+
- If any static file is renamed, please make sure to
86+
- Rename it in the `cacheAssets` array in `./src/service_worker.js`.
87+
- Increment the value of the `cacheName` variable. (Example: From `v2` to `v3`.)
88+
- Rename it in `./src/docinfo.html` if present.
89+
- **The `cacheName` should be updated just once per commit.**
90+
91+
#### Images
92+
93+
Images should have
94+
95+
- A solid colour background. (No transparent background images.)
96+
- A width and height of 600px, unless that distorts the picture or makes it illegible, in which case suitable dimensions can be used.
97+
- An `alt` attribute describing the image in a few words.
98+
99+
Example:
100+
101+
```
102+
image::file-name.ext[alt="image description", 600, 600, ...]
103+
```
104+
105+
## Language, Code and Syntax
106+
107+
- Pronouns are either omitted (preferred) or third person pronouns ('they', 'their', 'one', etc.) are used.
108+
109+
**Example**:
110+
111+
- `Code should be committed frequently.` ✔️ (Preferred)
112+
- `One should commit code frequently.` ✔️ (Accepted)
113+
- `You should commit code frequently.` ❌ (Not accepted)
114+
115+
- [Prettier](https://prettier.io) should be used to format code.
116+
117+
- The [`.prettierrc`](.prettierrc) config file can be found in the root directory.
118+
- Please use the Prettier's [VS Code extension](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) or [CLI](https://prettier.io/docs/en/cli.html) to format code before committing.
119+
120+
- The [AsciiDoc](https://marketplace.visualstudio.com/items?itemName=asciidoctor.asciidoctor-vscode) extension can be used, for syntax highlighting in `.adoc` files in VS Code.
121+
122+
- [Asciidoctor syntax](https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference) (Quick reference.)
123+
- Use the same syntax as used in the other files to maintain uniformity. Avoid using variations in syntax.
124+
- Writing in bullet points is preferable.
125+
- Bold, underline and italics should be used sparingly.
126+
- Surround single line commands or file names with a single 'back tick' (`).
127+
- Surround code snippets with three 'back ticks' (`\``).
128+
- External links should include a caret (`^`) at the end of the link text to open them in a new tab.
129+
130+
**Example**:
131+
132+
- `link:https://github.com[This is a link to another site^]` (Caret at the end for external links.)
133+
- `link:#_issues[This is a link to the same site]` (No caret at the end for internal links.)
134+
135+
- If external links are pasted as normal links, do following to open it in a new tab
136+
137+
**Example**: `link:https://github.com/HarshKapadia2/git_internals[github.com/HarshKapadia2/git_internals^]`
27138

28-
## Version Change Checklist
139+
- Links should have meaningful text.
29140

30-
Make sure the following changes are made when releasing a new version
141+
**Example**:
31142

32-
- Update the [changelog](CHANGELOG.md) with the appropriate version number and changes.
33-
- Refer to the [Keep a Changelog website](https://keepachangelog.com/en/1.0.0) for instructions.
34-
- Update the version in the [service worker](src/service-worker.js). (On line number 1.)
35-
- Update the version in the [index.adoc](src/index.adoc) file. (On line number 3.)
36-
- Create an annotated tag (`git tag -a vx.x.x -m "Release vx.x.x"`) on the latest commit of that release.
143+
- `It can be found in the link:https://docs.github.com[official documentation^].` ✔️ (Accepted)
144+
- `It can be found link:https://docs.github.com[here^].` ❌ (Not accepted)
37145

38146
## Further Help
39147

40-
If any further help is needed, do not hesitate to contact the author ([Harsh Kapadia](https://harshkapadia.me)) via Twitter [@harshgkapadia](https://twitter.com/harshgkapadia), [LinkedIn](https://www.linkedin.com/in/harshgkapadia) or e-mail ([[email protected]](mailto:[email protected])). An [issue](https://github.com/HarshKapadia2/asciidoctor-jet/issues) can be raised as well.
148+
If any further help is needed, do not hesitate to contact the owner ([Harsh Kapadia](https://harshkapadia.me)) via [OTC](https://ourtech.community), [Twitter](https://twitter.com/harshgkapadia), [LinkedIn](https://www.linkedin.com/in/harshgkapadia) or e-mail ([[email protected]](mailto:[email protected])). An [issue](https://github.com/HarshKapadia2/git_internals/issues) can be raised as well.

0 commit comments

Comments
 (0)