Skip to content

Commit 924117d

Browse files
AlexJSullyAlexJSully
authored
[docs] Created a docs directory and added Markdown linting (#513)
1 parent 34dc82b commit 924117d

File tree

11 files changed

+1145
-38
lines changed

11 files changed

+1145
-38
lines changed

‎.github/workflows/code-qa.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,8 @@ jobs:
3535
run: npm run prettier:check
3636
- name: Quality check - eslint
3737
run: npm run eslint:check
38+
- name: Quality check - type check
39+
run: npm run tsc
3840
- name: Quality check - cypress
3941
run: npm run e2e:headless
4042
- name: Build check

‎.github/workflows/markdown-lint.yml‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
name: Markdown Lint
2+
3+
on:
4+
push:
5+
branches: [main]
6+
paths:
7+
- '**/*.md'
8+
- '.github/workflows/markdown-lint.yml'
9+
pull_request:
10+
branches: [main]
11+
paths:
12+
- '**/*.md'
13+
- '.github/workflows/markdown-lint.yml'
14+
15+
jobs:
16+
lint-markdown:
17+
runs-on: ubuntu-latest
18+
19+
steps:
20+
- name: Checkout repository
21+
uses: actions/checkout@v4
22+
- name: Use Node.js ${{ matrix.node-version }}
23+
uses: actions/setup-node@v3
24+
with:
25+
node-version: ${{ matrix.node-version }}
26+
- name: Cache Node.js modules
27+
uses: actions/cache@v3
28+
with:
29+
path: ~/.npm
30+
key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
31+
restore-keys: |
32+
${{ runner.os }}-node-
33+
- name: Run installs
34+
run: npm ci --legacy-peer-deps
35+
- name: Run markdownlint on Markdown files
36+
run: npm run lint:markdown

‎.markdownlint.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"MD010": false,
3+
"MD013": false
4+
}

‎.markdownlintignore‎

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
1+
# compiled output
2+
/out-tsc
3+
dist
4+
tmp
5+
6+
# dependencies
7+
.pnp.js
8+
/.pnp
9+
jspm_packages/
10+
node_modules
11+
12+
# Visual Studio Code
13+
!.vscode/extensions.json
14+
!.vscode/launch.json
15+
!.vscode/settings.json
16+
!.vscode/tasks.json
17+
.vscode-test
18+
.vscode/*
19+
/.vscode
20+
21+
# IDEs and editors
22+
*.launch
23+
*.sublime-workspace
24+
.c9/
25+
.classpath
26+
.project
27+
.settings/
28+
/.idea
29+
service-account.json
30+
31+
# ORM Config
32+
ormconfig.*.*
33+
ormconfig.*.js
34+
ormconfig.js
35+
ormconfig.json
36+
37+
# misc
38+
.DS_Store
39+
.pem
40+
/.sass-cache
41+
/connect.lock
42+
/coverage
43+
/typings
44+
typings/
45+
Thumbs.db
46+
47+
# Next.js
48+
.next
49+
/.next/
50+
/out/
51+
52+
# Env files
53+
!.env.example
54+
!.env.masterpiece-studio-8ac80
55+
!.env.masterpiece-studio-production
56+
!.env.project
57+
.env
58+
.env*
59+
.env*.local
60+
.env.*
61+
.env.development.local
62+
.env.local
63+
.env.production.local
64+
.env.test.Local
65+
.staging_db_url
66+
!.env.vault
67+
68+
# Builds
69+
builds/
70+
build/
71+
72+
# vercel
73+
.vercel
74+
75+
# typescript
76+
*.tsbuildinfo
77+
tsconfig.tsbuildinfo
78+
79+
# ES Lint
80+
.eslintcache
81+
82+
# Service workers
83+
*.js.map
84+
sw.js
85+
sw.js.map
86+
workbox-*.js
87+
worker-*.js
88+
89+
# deploy
90+
.deploy/aws-kp.pem
91+
.deploy/settings-staging.json
92+
.deploy/settings.json
93+
94+
# Sentry
95+
.sentryclirc
96+
97+
# Flask
98+
.flaskenv*
99+
100+
# Cypress
101+
cypress/screenshots
102+
cypress/videos
103+
worker-@cypress/
104+
105+
# Logs
106+
*.log
107+
.pnpm-debug.log*
108+
/libpeerconnection.log
109+
lerna-debug.log*
110+
logs
111+
npm-debug.log
112+
npm-debug.log*
113+
testem.log
114+
yarn-debug.log*
115+
yarn-error.log
116+
yarn-error.log*
117+
118+
# Diagnostic reports (https://nodejs.org/api/report.html)
119+
report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
120+
121+
# nyc test coverage
122+
.nyc_output
123+
124+
# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
125+
.grunt
126+
127+
# Bower dependency directory (https://bower.io/)
128+
bower_components
129+
130+
# node-waf configuration
131+
.lock-wscript
132+
133+
# Snowpack dependency directory (https://snowpack.dev/)
134+
web_modules/
135+
136+
# npm cache directory
137+
.npm
138+
139+
# stylelint cache
140+
.stylelintcache
141+
142+
# Microbundle cache
143+
.rpt2_cache/
144+
.rts2_cache_cjs/
145+
.rts2_cache_es/
146+
.rts2_cache_umd/
147+
148+
# REPL history
149+
.node_repl_history
150+
151+
# Output of 'npm pack'
152+
*.tgz
153+
154+
# Yarn Integrity file
155+
.yarn-integrity
156+
157+
# parcel-bundler cache (https://parceljs.org/)
158+
.cache
159+
.parcel-cache
160+
161+
# Nuxt.js build / generate output
162+
.nuxt
163+
dist
164+
dist/**/*.js
165+
dist/**/*.js.map
166+
167+
# vuepress build output
168+
.vuepress/dist
169+
170+
# vuepress v2.x temp and cache directory
171+
.temp
172+
173+
# Docusaurus cache and generated files
174+
.docusaurus
175+
176+
# Serverless directories
177+
.serverless/
178+
179+
# FuseBox cache
180+
.fusebox/
181+
182+
# DynamoDB Local files
183+
.dynamodb/
184+
185+
# TernJS port file
186+
.tern-port
187+
188+
# yarn
189+
.yarn/cache
190+
.yarn/unplugged
191+
.yarn/build-state.yml
192+
.yarn/install-state.gz
193+
194+
# Firebase
195+
.firebase/
196+
197+
# nx cache
198+
.nx/cache
199+
200+
# Ignore minified files
201+
*.min.*

‎docs/components/projects.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# Projects Documentation
2+
3+
## Overview
4+
5+
This document explains how the projects grid is displayed and how to add new projects to the codebase.
6+
7+
## Projects Grid Display
8+
9+
The projects grid is displayed using the `ProjectsGrid` component located in [ProjectsGrid.tsx](../../src/components/projects/ProjectsGrid.tsx). This component creates a grid layout to showcase the projects.
10+
11+
### Key Elements
12+
13+
- **State Management**: The component uses the `useState` hook to manage whether to view all projects or only featured projects.
14+
- **Grid Layout**: The projects are displayed in a responsive grid layout using Material-UI's Grid and Stack components.
15+
- **Project Cards**: Each project is displayed as a card with a thumbnail image, project name, title, employer, and links to relevant resources.
16+
17+
### Flowchart
18+
19+
```mermaid
20+
flowchart LR
21+
A[ProjectsGrid Component] -->|Fetches| B[Projects Data]
22+
B --> C[Maps Projects to Grid Items]
23+
C --> D[Displays Project Cards]
24+
D --> E[Project Thumbnail]
25+
D --> F[Project Name]
26+
D --> G[Project Title - Employer]
27+
D --> I[Links]
28+
E --> J[Thumbnail Image]
29+
I --> K[Link Buttons]
30+
```
31+
32+
## Adding New Projects
33+
34+
To add new projects, you need to update the `projects` array in [projects.ts](../../src/data/projects.ts).
35+
36+
### Steps to Add a New Project
37+
38+
1. Open the [projects.ts](../../src/data/projects.ts) file.
39+
2. Add a new object to the projects array with the following structure: (see `Projects` interface in [projects.ts](../../src/data/projects.ts) for more details)
40+
41+
```json
42+
{
43+
"name": "Project Name",
44+
"id": "project-id", // unique identifier for the project (associated with the image file name or publication)
45+
"description": "Project description", // optional
46+
"employer": "Employer Name", // optional
47+
"employerURL": "https://employer-website.com", // required if employer is provided
48+
"title": "Job Title",
49+
"publication": "https://publication-url.com", // optional
50+
"type": "Employment", // or 'Personal Project', 'School (MSc)', etc.
51+
"url": "https://project-url.com", // optional
52+
"urls": [
53+
// this is used to create a series of buttons with links
54+
{
55+
"text": "Link Text",
56+
"tooltip": "Tooltip description",
57+
"icon": "IconComponent", // this is a JSX component
58+
"url": "https://link-url.com"
59+
}
60+
],
61+
"color": "#colorCode",
62+
"dates": {
63+
"startDate": "YYYY-MM",
64+
"endDate": "YYYY-MM" // or current if ongoing
65+
},
66+
"showcase": true, // or false
67+
"objectFit": "contain" // optional, cover is used if nothing is provided
68+
}
69+
```
70+
71+
### Adding Thumbnail Images
72+
73+
To add a thumbnail image for the new project, place the image in the appropriate directory:
74+
75+
1. **Navigate to the images directory**: Go to the [public image projects directory](../../public/images/projects).
76+
2. **Create a new directory**: Create a new directory with the project ID (e.g., new-project).
77+
3. **Add the thumbnail image**: Place the thumbnail image in the new directory and name it thumbnail. Recommended to use `.webp` format for better performance.
78+
79+
By following these steps, you can successfully add new projects to the projects grid.

‎docs/components/publications.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Publications Documentation
2+
3+
## Overview
4+
5+
This document explains how the publications list is displayed and how to add new publications to the codebase.
6+
7+
## Publications List Display
8+
9+
The publications list is displayed using the `Publications` component located in [Publications.tsx](../../src/components/publications/Publications.tsx). This component creates a list layout to showcase the publications.
10+
11+
### Key Elements
12+
13+
- **Styling**: The component uses inline styles to manage the appearance of publication metadata.
14+
- **List Layout**: The publications are displayed in a responsive list layout using Material-UI's Stack and Typography components.
15+
- **Publication Cards**: Each publication is displayed as a card with a title, authors, metadata, and an abstract.
16+
17+
### Flowchart
18+
19+
```mermaid
20+
flowchart LR
21+
A[Publications Component] -->|Fetches| B[Publications Data]
22+
B --> C[Maps Publications to List Items]
23+
C --> D[Displays Publication Cards]
24+
D --> E[Publication Title]
25+
D --> F[Publication Authors]
26+
D --> G[Publication Metadata]
27+
D --> H[Publication Abstract]
28+
```
29+
30+
## Adding New Publications
31+
32+
To add new publications, you need to update the `publications` array in [publications.ts](../../src/data/publications.ts).
33+
34+
### Steps to Add a New Publication
35+
36+
1. Open the [publications.ts](../../src/data/publications.ts) file.
37+
2. Add a new object to the publications array with the following structure:
38+
39+
```json
40+
{
41+
"title": "Publication Title",
42+
"authors": [
43+
"Author 1",
44+
"Author 2"
45+
// more authors
46+
],
47+
"abstract": "Abstract of the publication.",
48+
"doi": "10.1234/doi",
49+
"journal": "Journal Name",
50+
"date": "YYYY-MM-DD",
51+
"related-project": "project-id" // optional
52+
}
53+
```
54+
55+
By following these steps, you can successfully add new publications to the publications list.

0 commit comments

Comments
 (0)