Skip to content

Commit 1611f40

Browse files
andy-sorgeandy-sorge
committed
Begin writing readmes
1 parent d6d7581 commit 1611f40

File tree

4 files changed

+145
-22
lines changed

4 files changed

+145
-22
lines changed

‎README.md‎

Lines changed: 136 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,36 +1,150 @@
1-
This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
1+
# Palouse RoboSub Website
22

3-
## Getting Started
3+
The Palouse RoboSub website uses the Next.js React framework. It is built into
4+
static assets using GitHub Actions and hosted by GitHub Pages.
45

5-
First, run the development server:
6+
## Local Development
67

7-
```bash
8-
npm run dev
9-
# or
10-
yarn dev
11-
# or
12-
pnpm dev
13-
# or
14-
bun dev
8+
Make sure you have `Node.js` and `npm` installed.
9+
10+
After cloning the repo, run `npm install` to install the project's dependencies.
11+
Next run `npm run dev` and open [https://localhost:3000](https://localhost:3000).
12+
You can now see your changes in real time.
13+
14+
Before committing and pushing your changes, be sure to run `npm run lint` to ensure
15+
the code meets quality standards and `npm run build` to ensure that it will build
16+
correctly.
17+
18+
## MDX
19+
20+
All routes that are do not require functionality or interactivity are written in
21+
MDX. MDX is Markdown with the added ability to import and render React components.
22+
23+
### Markdown Syntax
24+
25+
GitHub-flavored Markdown rendering is supported. Markdown parsing is done by `remark`
26+
and the `remark-gfm` plugin extends support for GitHub-flavored specific syntax. To
27+
familiarize yourself with GitHub-flavored Markdown, visit GitHub's guide
28+
[Basic Writing and Formatting Syntax](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax)
29+
to get started, and subsequent guides cover more advanced topics. Markdown is
30+
intuitive and hierarchically structured like HTML, so it should be fairly easy to
31+
pick up.
32+
33+
#### Code
34+
35+
Language-aware syntax highlighting is supported in code blocks. The `remark-prism`
36+
plugin uses the `prism.js` syntax highlighter to deliver syntax highlighting, making
37+
code blocks much more readable. The syntax for creating a code block is as follows.
38+
39+
````markdown
40+
```<language>
41+
42+
int main()
43+
{
44+
45+
}
46+
47+
```
48+
````
49+
50+
Syntax highlighting will **not** work unless a language is specified. A full list of supported
51+
languages can be found [here](https://prismjs.com/#supported-languages).
52+
53+
#### Math
54+
55+
Advanced math formatting will be supported in the future, likely using LaTeX syntax.
56+
Coming hopefully by the end of October.
57+
58+
### React Components
59+
60+
React components allow drop-in additions of style and function to Markdown.
61+
62+
#### Importing
63+
64+
To use React components in an MDX file, you must first import it. Components are imported as
65+
[ECMAScript Modules](https://nodejs.org/api/esm.html#introduction), **not** as CommonJS modules.
66+
67+
Correct:
68+
```typescript jsx
69+
import Divider from '@/components/divider' // Default export
70+
```
71+
72+
```typescript jsx
73+
import {OfficersWrapper} from "@/components/officer-bio" // Named export
74+
```
75+
76+
Incorrect:
77+
```typescript jsx
78+
const divider = require('@/componsnts/divider') // CJS Require, DON'T DO THIS
79+
```
80+
81+
Import statements must be placed at the top of an MDX file before any content.
82+
83+
#### Usage
84+
85+
React components in MDX behave exactly as they do in TSX. If a component does not get
86+
all required props of the correct types, the build will likely fail. When working with
87+
React components in MDX files, there likely won't be syntax or error highlighting, which
88+
means attention to detail and knowledge of required props is necessary. It is also crucial
89+
to make sure all components have closing tags. Here are some examples.
90+
91+
With Children:
92+
```mdxjs
93+
<OfficerBio imageSrc="/officer-images/will.jpg">
94+
95+
## Will Smith
96+
97+
### President
98+
99+
</OfficerBio>
100+
```
101+
102+
Without Children:
103+
```mdxjs
104+
<Divider width="80%"/>
105+
```
106+
107+
#### Available Components
108+
109+
View the full list of available components [here](./react-components.md).
110+
111+
## Routing and Structure
112+
113+
The website uses file-based routing with the following structure:
15114
```
115+
(main)
116+
└── <url> // folder with url-safe name
117+
└── page.mdx // or page.tsx
118+
```
119+
120+
Pages **must** be named `page`, and rendering `.md` files is **not** supported.
121+
All MDX pages must use the `.mdx` file extension.
122+
123+
The `(main)` and `(docs)` folders are used to divide the routes so that separate
124+
`layout.tsx` files and global css styling can be used in the documentation.
125+
126+
New routes will **not** automatically be added to header or sitemap.
127+
I will implement this sometime in the future.
128+
129+
Further information on routing and structure can be found in the
130+
[Next.js Docs](https://nextjs.org/docs/app/getting-started/project-structure).
16131

17-
Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
132+
## Images
18133

19-
You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
134+
TODO
20135

21-
This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
136+
## Hosting, Build, and Deployment
22137

23-
## Learn More
138+
TODO
24139

25-
To learn more about Next.js, take a look at the following resources:
140+
## Editing Rules & Guidelines
26141

27-
- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
28-
- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
142+
TODO
29143

30-
You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
144+
## Blog
31145

32-
## Deploy on Vercel
146+
Guide for the Blog can be found [here](./blog.md).
33147

34-
The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
148+
## Technical Documentation
35149

36-
Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.
150+
Guide for the Technical Documentation can be found [here](./tech-docs.md).

‎blog.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Palouse RoboSub Blog
2+
3+
TODO

‎react-components.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Available React Components
2+
3+
TODO

‎tech-docs.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Palouse RoboSub Technical Documentation
2+
3+
TODO

0 commit comments

Comments
 (0)