Document the file structure of the repo (#113)

* Document the file structure of the repo * Minor simplification
civictechdc · Oct 3, 2024 · 3f6dceb · 3f6dceb
1 parent 89259eb
commit 3f6dceb
Showing 1 changed file with 45 additions and 15 deletions.
diff --git a/README.md b/README.md
@@ -1,23 +1,15 @@
 # Civic Tech DC Website
 
-Welcome! This is the repository for the website for Civic Tech DC. It is a static site built with [Jekyll](https://jekyllrb.com/). It is mostly HTML, Javascript, and CSS.
+Welcome! This is the repository for the website for Civic Tech DC. It is a static site built with [Jekyll](https://jekyllrb.com/). It is mostly Markdown/Liquid, HTML, Javascript, and CSS.
 
-## Getting Started
-
-### Quickstart with Codespaces
+## Table of contents
 
-[Github Codespaces](https://github.com/features/codespaces) is a free development environment based on VS Code that is run entirely in the browser. You can have your own copy of the Civic Tech DC Website up and running in a few clicks.
+1. [Getting Started](#getting-started)
+1. [Issues](#issues)
+1. [Contributing](#contributing)
+1. [File structure](#file-structure)
 
-1. Click "Fork" to make your own copy of the repository  
-   ![image](https://github.com/mchelen/codefordc-website/assets/30691/307cfd28-64cf-4178-9478-886736491036)
-2. Click "Create codespace on main"  
-   ![image](https://github.com/mchelen/codefordc-website/assets/30691/3bb1583d-c27f-41c0-9548-b9a76d21143c)
-3. Wait while your new Codespace starts, the dependencies will be installed and the web server will start automatically.  
-   ![image](https://github.com/mchelen/codefordc-website/assets/30691/409df32b-18b4-4376-b12a-fec61416349a)
-4. Click "Open in browser" to see your website running live! Click "Make public" if you would like to share with another user.  
-   ![image](https://github.com/mchelen/codefordc-website/assets/30691/8e764732-cdfa-48c5-84c4-a853b58b14d1)
-5. You can now modify the code and the website will automatically update.
-6. Commit your changes as usual, and open a pull request when ready to share back with the team.
+## Getting Started
 
 ### Local Development
 
@@ -65,3 +57,41 @@ If you notice a problem or have an idea for an improvement you can submit an [is
 Refer to the [contribution instructions](CONTRIBUTING.md) to contribute to this project. We have a [project board](https://github.com/orgs/civictechdc/projects/3) where we track issues and ideas to be implemented.
 
 Let us know if you get stuck in the Civic Tech DC Slack channel #civictechdc-website. Happy coding!
+
+## File Structure
+
+```
+.
+├── .devcontainer                 // GitHub Codespaces configuration
+├── .github                       // GitHub workflows
+├── .prettier.rc                  // Prettier linting and formatting configuration
+├── .prettierignore               // Files and directories that Prettier should ignore
+├── .python-version               // Python version
+├── .tool-versions                // Versions of Ruby, Node, etc.
+├── 404.html                      // Page shown for 404 not found errors
+├── CNAME                         // Used by GitHub Pages to host the website on a custom domain
+├── Gemfile                       // Ruby dependencies
+├── _config.yml                   // Jekyll configuration
+├── _includes                     // Page components that are included in other pages
+├── _layouts                      // Jekyll layouts. These are the templates that other pages are built on
+│   ├── base.html                 // Most basic page layout including HTML metadata, header, and footer
+│   ├── default.html              // Default page layout used by most pages
+│   └── hero-image.html           // Used by the homepage. Has a hero image and transparent hero text
+├── _projects                     // Collection of project files used to generate the list of projects displayed on the website
+├── _site                         // 🔒 Do not modify. This diretory is generated by Jekyll and is the actual files served by the web server
+├── assets                        // Assets referenced from within HTML/Markdown files
+│   ├── css                       // 🔒 Do not modify. Minified CSS generated by USWDS. If you want to make CSS changes do so in `./sass/custom/styles.scss`
+│   ├── fonts                     // Font files originally generated by USWDS
+│   ├── images                    // Image files
+│   ├── img                       // Image files generated by USWDS (should move this into a subdir of `images`)
+│   └── js                        // Javascript files
+│       └── meetup.js             // Used to fetch event data from Meetup.com and dynamically populate bare components rendered in HTML
+├── gulpfile.js                   // Gulp configuration. This is used for custom build steps and for building USWDS
+├── index.html                    // Homepage
+├── package.json                  // Javascript dependencies
+└── sass                          // SASS files for customizing CSS generated by USWDS
+    ├── custom
+    │   └── styles.scss           // Custom CSS that will be added to / overwrite USWDS CSS
+    ├── main.scss                 // USWDS SASS configuration
+    └── theme                     // USWDS SASS configuration
+```