readme guide

write a good readme :)

hey! im violet and ive been working on horizons for the last few months. one of the main reasons ive seen projects get denied is because of improper or poorly written readmes.

firstly, what is a readme?

a readme is a README.md file in your git repo, it’s supposed to tell the person looking at your repo information about the program. a readme is the first thing someone will see when your look at your project, you want to make a good impression! people have seen 1000 different projects, make yours stand out :)

readmes are written in markdown format, which is very common everywhere, this guide is written in markdown! here are some of the most common bits of formatting you’ll use:

what it does	how you write it
title / heading	`# big title`, `## smaller`, `### smol`
bold	`bold text`
italic	`italic text`
bold + italic	`*bold italic text*`
~~strikethrough~~	`~~crossed out~~`
link	`[text to show](https://your-link.com)`
image / gif embed	`![alt text](https://your-link.com/cool.gif)`
inline code	`code`
code block	```language ... ```
bullet list	`- item`
numbered list	`1. item`
quote	`> quoted text`

what should be in a readme?

readmes should include:

information about your project, what is it, what does it do, etc.
your tech stack (what programs / frameworks / languages were used in this project)
information about how it was made, problems you had to fix, etc.
how to run the project! development instructions, links to dependencies, etc.
demo links to your projects so people can try it out without having to download things
screenshots screenshots screenshots! show off the coolest and most interesting parts of your project
disclosure on how much ai was used and for what

a readme should NOT:

BE AI GENERATED. YOU KNOW YOUR PROJECT, NOT AN AI. PLEASE PLEASE PLEASE DON’T AI GENERATE IT. I WILL BE SAD.
LACK AN INSTALLATION GUIDE.

im still a little confused?

if you’re struggling, ask yourself these questions (for the more creative parts, the technical parts should be pretty easy)

What your project is/does?
Why you made your project?
How your project was made?

development example!

example of build and running commands, stolen from phthallo’s site :)

### Development

1. Clone the source code to your device
```sh
git clone https://github.com/phthallo/site-v1 && cd site-v1
```

2. Install the project's dependencies
```sh
bun install
```

3. Start the development server on `localhost:4321`
```sh
bun run dev
```

4. Build the site to `/dist`
```sh
bun run build
```

basic readme example!

# SUPER AWESOME PROJECT!!!
hey! this is text explaining what my awesome project is :)
here's an AWESOME gif of my project!
![awesome gif](https://user-cdn.hackclub-assets.com/019f0195-7b3c-7a6b-a8c9-ba589c575ae6/blahajmeow.gif)
## HOW THIS WAS MADE
*example for this site*
this project was made with [astro](https://astro.build) using the [starlight](https://starlight.astro.build/) template :D

## heres how to run the project :)
1. Clone the source code to your device
```sh
git clone https://github.com/vivithequeen/horizons-guides.git
```

2. Install the project's dependencies
```sh
npm install
```

3. Start the development server on `localhost:4321`
```sh
npm run dev
```

4. Build the site to `/dist`
```sh
npm run build
```
and be joyous!

## AI DISCLOSURE
what did you use ai for on this project? for example for this site:
ai was used to copy css styling from template screenshots

here are some amazing examples of readmes:

TLDR

don’t use ai, write settup instructions, have fun, make a good impression!

written with <3 by violet | contact me via slack or violet@hackclub.com