Skip to content

Commit 8ee9d54

Browse files
authored
Revise contributing section of readme
1 parent ba2181f commit 8ee9d54

File tree

1 file changed

+18
-15
lines changed

1 file changed

+18
-15
lines changed

README.md

Lines changed: 18 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -95,6 +95,21 @@ Changes to `package-lock.json` and `yarn.lock` files should only be committed wh
9595
- Updating an existing dependency: Running an update for a package will adjust these files to reflect the new versions.
9696
- Removing a dependency: Uninstalling a package will update these files to remove the reference to the dependency.
9797

98+
### Content File Formats
99+
100+
**Use `.md` or `.mdx` file formats** MDX is a markdown format that allows embedded JSX components for more flexibility. Refer to the Docusaurus Docs page [MDX and React](https://docusaurus.io/docs/markdown-features/react) for information on MDX syntax and capabilities.
101+
102+
**Always link using explicit heading IDs** when adding or editing headings in a `.md` or `.mdx` file. This prevents broken links if heading text changes later. For example:
103+
104+
```markdown
105+
### My Important Section{#my-important-section}
106+
```
107+
Then, you can link to this section using:
108+
109+
```markdown
110+
[Link to my section](#my-important-section)
111+
```
112+
98113
### Add or Edit Feature Cards
99114

100115
Feature Cards on the website homepage highlight the key features of the PEcAn Project.
@@ -177,28 +192,16 @@ tags: [gsoc, gsoc21]
177192
---
178193
```
179194

195+
196+
<!-- These screenshots are large and don't appear to be in the right place, if necessary
180197
## Screenshots
181198
182199
This section contains screenshots of website's homepage in light and dark theme.
183200
184201
![LightTheme](screenshots/light.png)
185202
186203
![DarkTheme](screenshots/dark.png)
187-
188-
## Editing a Documentation File
189-
The PEcAn documentation is a crucial part of the project. We aim to make it comprehensive, accurate, and easy to navigate. When contributing to documentation, please keep the following in mind:
190-
191-
* **Always use explicit heading IDs** when adding or editing headings in documentation file(`.mdx`). This prevents broken links if heading text changes later. For example:
192-
193-
```markdown
194-
### My Important Section{#my-important-section}
195-
```
196-
Then, you can link to this section using:
197-
198-
```markdown
199-
[Link to my section](#my-important-section)
200-
```
201-
* **Use appropriate file formats**, primarily Markdown (`.md`) and MDX (`.mdx`). MDX allows embedding JSX components within documentation for more flexibility. Refer to [Docusaurus Docs](https://docusaurus.io/docs) for MDX syntax.
204+
-->
202205

203206
## Next Steps
204207

0 commit comments

Comments
 (0)