Skip to content

Commit c240f2a

Browse files
Arisamiganovanai
Arisamiga
and
novanai
authored
Documentation for atlas (#54)
This Pull Request adds documentation on the [Atlas](https://github.com/redbrick/atlas) website with information regarding 11ty, project structure and how to add new pages. --------- Co-authored-by: nova <110734810+novanai@users.noreply.github.com>
1 parent 8a7e21e commit c240f2a

2 files changed

Lines changed: 172 additions & 0 deletions

File tree

‎docs/webgroup/atlas.md‎

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
---
2+
id: atlas
3+
aliases:
4+
- Atlas
5+
tags:
6+
- webgroup
7+
- website
8+
title: Atlas
9+
---
10+
11+
# Atlas (Redbrick Website)
12+
13+
Atlas is Redbrick's static website, built with [Eleventy (11ty)](https://www.11ty.dev/) and styled with Tailwind CSS + PostCSS. The site output is generated into `dist/` and can be served locally during development, or built into a production container served by Nginx.
14+
15+
## Quick links
16+
17+
- Live site: <https://redbrick.dcu.ie>
18+
19+
## Tech stack / tooling
20+
21+
- [**Node.js**](https://nodejs.org/en): `^18.17 || ^20`
22+
- **Package manager**: [Yarn](https://yarnpkg.com/) (`yarn@4.1.0`, via Corepack)
23+
- **Static site generator**: [Eleventy](https://www.11ty.dev/) (`@11ty/eleventy`)
24+
- **Templating**: [Nunjucks](https://mozilla.github.io/nunjucks/) (`.njk`) + Markdown (`.md`) + HTML
25+
- **CSS**: [Tailwind CSS](https://tailwindcss.com/) + [PostCSS](https://postcss.org/) (Autoprefixer)
26+
- **Search**: [Pagefind](https://pagefind.app/)
27+
- **Container build/runtime**: multi-stage Docker build (Node build → Nginx runtime)
28+
- **CI/CD**: [GitHub Actions](https://github.com/features/actions) (build/publish + deploy)
29+
30+
## Development
31+
32+
Install dependencies:
33+
34+
```bash
35+
corepack enable
36+
yarn
37+
```
38+
39+
Run a dev server:
40+
41+
```bash
42+
yarn dev
43+
```
44+
45+
Build for production (outputs to `dist/`):
46+
47+
```bash
48+
yarn build
49+
```
50+
51+
## Build output
52+
53+
- Eleventy input: `src/site`
54+
- Eleventy output: `dist/`
55+
56+
(These are configured in `package.json` under the `eleventy.dir` section.)
57+
58+
## File structure breakdown
59+
60+
> [!NOTE]
61+
> `dist/` is generated at build time and is not committed.
62+
63+
```text
64+
.
65+
├── .github/
66+
│ ├── deploy/
67+
│ │ ├── production.hcl # Nomad job spec for production deployment
68+
│ │ └── review.hcl # Nomad job spec for review (branch) deployments
69+
│ └── workflows/
70+
│ ├── build.yml # Build & publish Docker image to GHCR
71+
│ └── deploy.yml # Deploy workflow (prod + review environments)
72+
├── eleventy/
73+
│ ├── filters/
74+
│ │ └── slugify.js # Custom filter(s) for templates
75+
│ ├── parsers/
76+
│ │ └── markdown.js # Markdown parser configuration
77+
│ ├── plugins/
78+
│ │ ├── git-build.js # Build metadata from git
79+
│ │ ├── navigation-render.js # Navigation rendering helper
80+
│ │ └── pagefind.js # Pagefind integration
81+
│ └── utils/ # Eleventy utility code (helpers)
82+
├── src/
83+
│ ├── _data/ # Eleventy data files (global/site data)
84+
│ ├── _includes/ # Includes/partials used by templates
85+
│ ├── _layouts/ # Layout templates
86+
│ └── site/ # Main Eleventy input directory
87+
│ ├── assets/ # Static assets (images, fonts, etc.)
88+
│ ├── index.md # Homepage content
89+
│ ├── links.md # Links page content
90+
│ └── 404.md # 404 page content
91+
├── .dockerignore
92+
├── .editorconfig
93+
├── .eleventy.js # Eleventy config entrypoint
94+
├─ .eleventyignore
95+
├── .gitattributes
96+
├── .gitignore
97+
├── Dockerfile # Multi-stage build (Node -> Nginx)
98+
├── nginx.conf # Nginx config for serving the built site
99+
├── postcss.config.js # PostCSS configuration
100+
├── tailwind.config.js # Tailwind configuration
101+
├── package.json # Scripts + dependencies + Eleventy directory config
102+
├── yarn.lock
103+
└── LICENSE
104+
```
105+
106+
## Docker
107+
108+
A multi-stage Docker build is used:
109+
110+
1. **Build stage**: installs deps + runs `yarn build` to generate `dist/`
111+
2. **Production stage**: serves `dist/` via `nginx`
112+
113+
## Deployments (high-level)
114+
115+
- Docker images are built and published via GitHub Actions.
116+
- Deployments use Nomad job specifications in `.github/deploy/` for:
117+
- **Production** (`production.hcl`)
118+
- **Review** per-branch (`review.hcl`)
119+
120+
## Running locally with Docker
121+
122+
To run the site locally in a Docker container (serving the production build via Nginx):
123+
124+
1. Build the Docker image:
125+
126+
```bash
127+
docker build -t redbrick-atlas .
128+
```
129+
130+
2. Run the container:
131+
132+
```bash
133+
docker run -p 8080:80 redbrick-atlas
134+
```
135+
136+
3. Access the site at [`http://localhost:8080`](http://localhost:8080).
137+
138+
> [!NOTE]
139+
> When making changes the docker image will need to be re-built and re-run to see the changes reflected in the container.
140+
141+
## Creating a new page
142+
143+
1. Create a new Markdown file in `src/site/` (e.g., `src/site/new-page.md`).
144+
2. Add front matter and content:
145+
146+
```markdown
147+
---
148+
layout: default.njk
149+
---
150+
<main>
151+
{% include "newpage.njk" %}
152+
</main>
153+
```
154+
155+
> [!NOTE]
156+
> We advise using a [nunjucks include](https://mozilla.github.io/nunjucks/templating.html#include) for the page content to keep the Markdown file clean and focused on content, while the layout and styling can be handled in the included Nunjucks template.
157+
158+
3. Create the corresponding Nunjucks template in `src/_includes/` (e.g., `src/_includes/newpage.njk`) and add your HTML content there.
159+
4. Link to the new page from the navigation or other pages as needed.
160+
161+
Navigation links are defined in `src/_data/site.yml` under navigation and global taking a `- text` which is the text shown in the nav and a `link` which is the path to the page (e.g., `/new-page` for `src/site/new-page.md`).
162+
163+
## Outside contributions
164+
165+
- Contributions to the website are always welcome!
166+
167+
> [!WARNING]
168+
> If you want to have the preview deployment for a Pull request the PR must be opened from a branch in the main repository (not a fork) due to GitHub Actions permissions. If you want to open a PR from a fork, you will need to merge it into a branch in the repoisitory and open the PR from there to have the preview deployment. If you are not able to do this, ask a webgroup member to open the PR for you or to merge your PR into a branch in the repository.

‎docs/webgroup/index.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,3 +18,7 @@ Read more about how the webgroup operates in [open governance](https://redbrick.
1818
### [Blockbot](blockbot.md)
1919

2020
A Discord bot, written in Python, that is maintained by the Redbrick Webgroup.
21+
22+
### [Atlas (Redbrick Website)](atlas.md)
23+
24+
A static website, written in Eleventy (11ty), that is maintained by the Redbrick Webgroup. The website is hosted at <https://redbrick.dcu.ie>.

0 commit comments

Comments
 (0)