|
1 | | -<div align="center"> |
2 | | - <a href="https://cloudcomputingclub.cs.uml.edu/"> |
3 | | - <img src="./club-logo.png" alt="Logo" width="50%" height="50%"/> |
4 | | - </a> |
5 | | - <hr> |
6 | | - <h1>The UML Cloud Computing Club Website</h1> |
7 | | -</div> |
8 | | - |
9 | | - |
10 | | -This is the official repo for the UML Cloud Computing Club's website. |
11 | | - |
12 | | -The website is implemented using [Docusaurus](https://docusaurus.io/) and some fundamental [ReactJS](https://react.dev/). |
13 | | - |
14 | | - |
15 | | -## 👨💻 Documentation and Tutorials Contribution Guidelines |
16 | | - |
17 | | -To edit the documentation sections or the tutorials section of the website: |
18 | | - |
19 | | -1. Create a new branch from the **main** branch |
20 | | -2. Make the appropriate edits within this branch |
21 | | -3. Make an eventual pull request for the branch to be merged into **main** |
22 | | -4. Await approval or make the reviewers' requested changes and resubmit |
23 | | - |
24 | | - |
25 | | -All markdown files containing documentation details of the projects are in **docs/projects/** with the project's name marking the folder that contain's it's documentation |
26 | | - |
27 | | -All markdown files containing tutorial details are in **docs/tutorials/** with the specific tutorial's name marking the folder that contain's it's files. |
28 | | - |
29 | | -All markdown files should follow Docusaurus's guidelines for folder structure for autogenerating the UI and pagination. More details are available at the [Docusaurus Docs](https://docusaurus.io/docs/sidebar/autogenerated). |
30 | | - |
31 | | -## 🎉Acknowledgements |
32 | | -[](https://github.com/UMLCloudComputing/UMLCloudComputing.github.io/graphs/contributors) |
33 | | - |
| 1 | +<div align="center"> |
| 2 | + <a href="https://cloudcomputingclub.cs.uml.edu/"> |
| 3 | + <img src="./club-logo.png" alt="Logo" width="50%" height="50%"/> |
| 4 | + </a> |
| 5 | + <hr> |
| 6 | + <h1>The UML Cloud Computing Club Website</h1> |
| 7 | +</div> |
| 8 | + |
| 9 | + |
| 10 | +This is the official repo for the UML Cloud Computing Club's website. |
| 11 | + |
| 12 | +The website is implemented using [Docusaurus](https://docusaurus.io/) and some fundamental [ReactJS](https://react.dev/). |
| 13 | + |
| 14 | + |
| 15 | +## 👨💻 Documentation and Tutorials Contribution Guidelines |
| 16 | + |
| 17 | +To edit the documentation sections or the tutorials section of the website: |
| 18 | + |
| 19 | +1. Create a new branch from the **main** branch |
| 20 | +2. Make the appropriate edits within this branch |
| 21 | +3. Make an eventual pull request for the branch to be merged into **main** |
| 22 | +4. Await approval or make the reviewers' requested changes and resubmit |
| 23 | + |
| 24 | + |
| 25 | +All markdown files containing documentation details of the projects are in **docs/projects/** with the project's name marking the folder that contain's it's documentation |
| 26 | + |
| 27 | +All markdown files containing tutorial details are in **docs/tutorials/** with the specific tutorial's name marking the folder that contain's it's files. |
| 28 | + |
| 29 | +All markdown files should follow Docusaurus's guidelines for folder structure for autogenerating the UI and pagination. More details are available at the [Docusaurus Docs](https://docusaurus.io/docs/sidebar/autogenerated). |
| 30 | + |
| 31 | +## 🛤️ Adding New Repository to Project Docs |
| 32 | + |
| 33 | +To add a new project's docuemtnation onto the project docs section of the website, you must meet a few pre-reqs: |
| 34 | + |
| 35 | +1. The project must be a remote git repository (Github, BitBucket, etc) |
| 36 | +2. The project's repository must contain folder with the following structure: <br/> |
| 37 | + ``` shell |
| 38 | + docs |
| 39 | + └── web_docs |
| 40 | + └── *docs*<br/> |
| 41 | + _category_.json |
| 42 | + ``` |
| 43 | +3. The project's documentation files must follow [Docusaurus's](https://docusaurus.io/docs/create-doc) doc creation guidelines. <br/> This inlcudes having proper front-matter and an appropriate `_category_.json` file for each folder. |
| 44 | + |
| 45 | +Front Matter requirements: |
| 46 | +1. All markdown files must have the following front-matter: (`#` is an integer) |
| 47 | +``` text |
| 48 | +--- |
| 49 | +sidebar_position: # |
| 50 | +--- |
| 51 | +``` |
| 52 | + |
| 53 | +2. Each folder and subfolder must contain a `_category_.json` file. Each `.json` file should be contain the following content: |
| 54 | +``` json |
| 55 | +{ |
| 56 | + "label": "My Project", |
| 57 | + "position": #, |
| 58 | + "link": { |
| 59 | + "type": "generated-index" |
| 60 | + } |
| 61 | +} |
| 62 | +``` |
| 63 | +Here the label should be your own. The label indicates the labeled name of the folder or subfolder to be shown. IE project name (`My Project`), subsection name (`Excersices`), etc. <br/> |
| 64 | +The position value should also be customized to an `integer` representing the position of your folder or subfolder relative to other subfolders. |
| 65 | + |
| 66 | +> [!IMPORTANT] |
| 67 | +> Be sure to check the position values of current project docs. Do not place conflicting position values to other projects.<br/> In the example below, both `react-mui-resume` and `rowdybot` cannot have the same position values within their `_category_.json` files. Avoid these conflicts in your `_category_.json` files! |
| 68 | + |
| 69 | +``` shell |
| 70 | +react-mui-resume |
| 71 | +│ ├── _category_.json |
| 72 | +│ └── Intro.md |
| 73 | +├── rowdybot |
| 74 | +│ ├── _category_.json |
| 75 | +│ └── Intro.md |
| 76 | +``` |
| 77 | + |
| 78 | + |
| 79 | + |
| 80 | +### In order to add your project: |
| 81 | +1. Create a new branch from the **main** branch |
| 82 | +2. Name the branch with the following convention: `feat: Add new project docs: PROJECTNAME` with `PROJECTNAME` being the name of your project. |
| 83 | +3. Run the following command from within the root directory of your new branch: |
| 84 | + ``` shell |
| 85 | + git submodule add REPO_URL submodules/ |
| 86 | + ``` |
| 87 | + `REPO_URL` is the **URL** for your repository. Do not confuse this with the `.git` link to your repository. It's specically the **URL**. <br/> |
| 88 | + IE for this very Github repository it's: https://github.com/UMLCloudComputing/UMLCloudComputing.github.io |
| 89 | +4. Open the `submodules_automation.sh` file for editing. Add the proper name of your git repository into the sequence called `projects`. Be sure to include a **space** between your repository name and the name of the previous repository. The **proper** name of your repository is typically simply the name of your repository. To be extra sure, confirm with the name of the folder added to `submodules/` marking your project. That folder is named the **proper** name of your repository. |
| 90 | +5. Run the script you just edited by calling the command `./submodules_automation.sh` or `bash submodules_automation.sh` from the root directory of your branch. |
| 91 | +6. Now your docs have been imported to the website's collection of docs. All that's left is to stage, commit and push the changes from your branch to the main branch. |
| 92 | +7. After your pull request is approved, your project's docs will be visible in production on the website! |
| 93 | +
|
| 94 | +
|
| 95 | +## 🎉Acknowledgements |
| 96 | +[](https://github.com/UMLCloudComputing/UMLCloudComputing.github.io/graphs/contributors) |
| 97 | +
|
34 | 98 | ### Happy Coding! |
0 commit comments