diff --git a/docs/website/docs-ufosc/_category_.json b/docs/website/docs-ufosc/_category_.json new file mode 100644 index 0000000..0b38f0d --- /dev/null +++ b/docs/website/docs-ufosc/_category_.json @@ -0,0 +1,6 @@ +{ + "position": 3, + "label": "Documentation Site", + "collapsible": true, + "collapsed": false, +} diff --git a/docs/website/docs-ufosc/docusaurus.md b/docs/website/docs-ufosc/docusaurus.md new file mode 100644 index 0000000..e1dd6de --- /dev/null +++ b/docs/website/docs-ufosc/docusaurus.md @@ -0,0 +1,143 @@ +--- +title: Configuring Docusaurus +description: OSC Docs Configuring Docusaurus +sidebar_position: 7 +--- + +# Configuring Docusaurus + +This guide discusses modifying the `docusaurus.config.js` file, which includes configurations of the website's features and design template. + +## Introduction + +The docusaurus.config.js file is a crucial configuration file in a Docusaurus project. It allows you to customize various aspects of your documentation site, including the site metadata, themes, plugins, and more. In this guide, we'll walk you through the essential options you can modify in the docusaurus.config.js file to tailor your Docusaurus project to your needs. + +## Prerequisites + +Ensure you've installed the project's repository and its dependencies. If not, refer to the [Installation](/docs/website/docs-ufosc/installation) guide. + +## Step 1: Locate the docusaurus.config.js File +In your Docusaurus project directory, you'll find the `docusaurus.config.js` file. It's at the root level of your project. Open this file in a text editor of your choice. + +## Step 2: Basic Site Configuration + +### a. 'title' and 'tagline' + +```js title="docusaurus.config.js" +const config = { + title: 'My Documentation Site', + tagline: 'Documentation made easy', + // ... other configuration options ... +} +``` + +Modify the title and tagline properties to reflect the name and tagline of your documentation site. These will appear in the site header and browser tab. + +### b. url and baseUrl + +```js title="docusaurus.config.js" +const config = { + // ... + url: 'https://www.example.com', + baseUrl: '/', + // ... other configuration options ... +} +``` + +Update the url and baseUrl properties to match the URL where you'll host your documentation site. If your site is hosted in a subdirectory, adjust the baseUrl accordingly. + +## Step 3: Customize Themes + +### a. 'themeConfig' + +```js title="docusaurus.config.js" +const config = { + // ... + themeConfig: { + navbar: { + title: 'My Documentation Site', + logo: { + alt: 'My Logo', + src: 'img/logo.png', + }, + // ... other navbar options ... + }, + // ... other theme configuration options ... + }, +} +``` + +The `themeConfig` option allows you to customize the appearance and behavior of your documentation site. For example, you can modify the navbar's title, logo, and other settings to fit your branding. + +## Step 4: Configure the Sidebar + +```js title="docusaurus.config.js" +const config = { + // ... + themeConfig: { + sidebar: { + // Sidebar items for the documentation pages + docs: [ + { + type: 'doc', + id: 'getting-started', + }, + { + type: 'category', + label: 'Tutorials', + items: ['tutorial-1', 'tutorial-2'], + }, + ], + // ... other sidebar configuration options ... + }, + // ... other theme configuration options ... + }, +} +``` +In the `sidebar` option, you can organize your documentation pages and group them under categories. You can specify individual documentation pages using `type: 'doc'` and `id`, or you can create category-based groups using `type: 'category'`. + + +## Step 5: Add Plugins (Optional) + +```js title="docusaurus.config.js" +const config = { + plugins: [ + // Add your plugins here + ], + // ... other configuration options ... +} +``` + +If you want to enhance your documentation site with additional features, you can add plugins. Docusaurus has a rich ecosystem of plugins that you can integrate to extend functionality. + +For instance, the OSC Docs website uses the "plugin-content-docs" plugin to create multiple documentation sites (as opposed to the default option of only one). To create a documentation site, first make sure that you've created a subfolder for your project in the 'docs' directory. Then, navigate to the plugins section in docusaurus.config.js and append your desired information into the array: +```js title="docusaurus.config.js" +{ + plugins: [ + [ + '@docusaurus/plugin-content-docs', + { + id: 'website', // a unique ID for your project + path: 'docs/website', // the path to your docs folder + routeBasePath: 'docs/website', // the path on the website's URL + editUrl: 'https://github.com/ufosc/osc-docs' + } + ], + ] +} +``` + +## Step 6: Save and Apply Changes + +Once you have made the desired modifications to the docusaurus.config.js file, save the changes and close the file. + +## Step 7: Preview Your Changes + +To see your modifications in action, run the development server (you must open a terminal to the project's root folder): + +```bash +npm start +``` +Now, open your web browser and navigate to http://localhost:3000 to preview your updated Docusaurus documentation site with the custom configurations. + +For more usage documentation, refer to the [Usage](/docs/website/docs-ufosc/usage) section. diff --git a/docs/website/docs-ufosc/installation.md b/docs/website/docs-ufosc/installation.md new file mode 100644 index 0000000..2cec53f --- /dev/null +++ b/docs/website/docs-ufosc/installation.md @@ -0,0 +1,100 @@ +--- +title: Installation +description: OSC Docs Installation +sidebar_position: 2 +--- + +# Installation + +## Prerequisites + +The OSC Docs project requires certain dependencies to be installed on the user's machine. + +### System Development Libraries + +If you are using macOS, you will need to install Xcode Command Line Tools. These tools provide essential development libraries and utilities, including Git, which is required for the OSC Docs project and other development tasks. + +#### Installing Xcode Command Line Tools: + +1. Open Terminal, which can be found in the Utilities folder within the Applications folder, or you can use Spotlight search (Cmd + Space) and type "Terminal" to open it. +2. Enter the following command: +```bash +xcode-select --install +``` +3. A dialog will pop up asking you to install the Xcode Command Line Tools. Click "Install" and follow the on-screen instructions. + +#### Build Essential (for Linux) + +If you are using a Linux distribution, you'll need to ensure you have the `build-essential` package installed. This package includes essential tools for building software on a Linux system, such as compilers and libraries. + +For Debian-based distributions (e.g., Ubuntu): +```bash +sudo apt update +sudo apt install build-essential +``` + +For Red Hat-based distributions (e.g., Fedora): +```bash +sudo dnf groupinstall "Development Tools" +``` + +For Arch Linux: +```bash +sudo pacman -S base-devel +``` + +The installation process will depend on your specific Linux distribution. Once build-essential is installed, you'll have the necessary tools for development on your Linux system. + +### Git + +Git is a version control system that's necessary for installing the project and collaborating with others. + +1. Visit the official Git website: https://git-scm.com/downloads +2. Download the installer for your operating system (Windows, macOS, or Linux). +3. Run the installer and follow the on-screen instructions to install Git. + +### NodeJS & NPM + +The OSC Docs website is built using NodeJS, so you'll need to have it installed prior to running the site. + +1. Visit the official Node.js website: https://nodejs.org/ +2. Download the LTS (Long-Term Support) version for your operating system. +3. Run the installer and follow the installation instructions. +4. After installation, open your command line (Terminal on macOS/Linux, Command Prompt on Windows) and run the following commands to verify that Node.js and NPM are installed: +```bash +node -v +npm -v +``` + +### Text Editor + +You'll need a text editor to write and modify your Docusaurus project files. Many developers prefer using code editors with syntax highlighting and other useful features. + +Some popular text editors and Integrated Development Environments (IDEs) for web development include: + +1. Visual Studio Code: https://code.visualstudio.com/ +2. Sublime Text: https://www.sublimetext.com/ +3. Atom: https://atom.io/ +4. JetBrains WebStorm: https://www.jetbrains.com/webstorm/ +5. Emacs https://www.gnu.org/software/emacs/ (requires IQ > 160). + +Choose the one that suits your preferences and install it on your system. + +## Cloning the Repository + +Cloning the repository requires having Git installed. 'Cloning' will install a copy of the project. To install OSC Docs on your system, run: + +```bash +git clone https://github.com/ufosc/osc-docs.git +``` + +## Installing Dependencies + +To install the project's dependencies, run: + +```bash +cd osc-docs +npm i +``` + +You're now ready to start using the OSC Docs website. Continue to the [Usage](/docs/website/docs-ufosc/usage) to start the development server. diff --git a/docs/website/docs-ufosc/introduction.md b/docs/website/docs-ufosc/introduction.md new file mode 100644 index 0000000..a2d7270 --- /dev/null +++ b/docs/website/docs-ufosc/introduction.md @@ -0,0 +1,25 @@ +--- +title: Introduction +description: ufosc.org +sidebar_position: 1 +--- + +# Introduction + +[![standard-readme compliant](https://img.shields.io/badge/readme%20style-standard-brightgreen.svg?style=flat-square)](https://github.com/RichardLitt/standard-readme) ![GitHub Workflow Status (with event)](https://img.shields.io/github/actions/workflow/status/ufosc/osc-docs/node.js.yml) [![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com) ![GitHub](https://img.shields.io/github/license/ufosc/osc-docs) ![GitHub issues](https://img.shields.io/github/issues/ufosc/osc-docs) + +The OSC Docs website is a source of truth for projects and club activity at the University of Florida's Open Source Club. More specifically, it hosts user and developer documentation for the various projects started each semester. This project uses [Docusaurus](https://docusaurus.io/) to quickly and conveniently generate static sites from [Markdown](https://www.markdownguide.org/basic-syntax/) files. + +Unlike the [main OSC website](https://ufosc.org), the docs website emphasizes content delivery, accessibility, and ease of content creation (especially for non-technical users). This is beyond the capabilities and scope of the main site's native content management system, hence the need for a separate documentation site. + +The source code is available on the Open Source Club's [GitHub page](https://github.com/ufosc) under the [AGLP-3.0-or-later](https://spdx.org/licenses/AGPL-3.0-or-later) license, and the site is hosted at [docs.ufosc.org](https://docs.ufosc.org). To get started with contributing to the osc docs, start by [installing the project](/docs/website/docs-ufosc/installation). + +
+ +## Index +* [Installation](/docs/website/docs-ufosc/installation): Instructions on installing the project and its dependencies. +* [Usage](/docs/website/docs-ufosc/usage): Instructions on setting up a local development server and using the project. +* [Markdown](/docs/website/docs-ufosc/markdown): Introduction to the Markdown language. +* [Documentation](/docs/website/docs-ufosc/writingdocs): Creating documentation sites and managing their contents. +* [Static Pages](/docs/website/docs-ufosc/static-pages): Guide to creating non-documentation static pages. +* [Configuring Docusaurus](/docs/website/docs-ufosc/docusaurus): Guide to modifying the Docusaurus website template. diff --git a/docs/website/docs-ufosc/markdown.md b/docs/website/docs-ufosc/markdown.md new file mode 100644 index 0000000..6bbd67e --- /dev/null +++ b/docs/website/docs-ufosc/markdown.md @@ -0,0 +1,172 @@ +--- +title: Markdown +description: OSC Docs Markdown +sidebar_position: 4 +--- + +# Markdown + +Markdown is a lightweight markup language that allows you to write formatted text using a simple and intuitive syntax. It is commonly used for creating documentation, README files, blog posts, and more. This guide will introduce you to the basics of Markdown, enabling you to create formatted documents effortlessly. + +Markdown plays a crucial role in the Docusaurus module as it is the primary content format for creating documentation pages, making it an essential part of the documentation workflow. This is a markdown language guide, to learn more about writing documentation with markdown, see [Documentation](/docs/website/docs-ufosc/markdown). + +:::tip + +To view this file's markdown code, scroll to the bottom of the page and click on "Edit this page." + +::: + +:::tip + +You can test out writing code in markdown by using an [online markdown editor](https://dillinger.io/). + +::: + +## Headers + +Headers are defined using hash (#) symbols before the text and demarcate sections in your documentation (titles, subtitles, and their constituent content). The number of hash symbols determines the header level. For example: + +```markdown title="Markdown" +# Heading 1 +## Heading 2 +### Heading 3 +#### Heading 4 +``` + +In Docusaurus, the above example will appears as below: + +:::note Docusaurus Example + +# Header 1 +## Header 2 +### Header 3 +#### Header 4 + +::: + +## Text Formatting + +You can apply various text formatting styles in Markdown: + + * Bold: Enclose the text with double asterisks (`**text**`) or double underscores (`__text__`). + * Italic: Enclose the text with single asterisks (`*text*`) or single underscores (`_text_`). + * Strikethrough: Enclose the text with double tildes (`~~text~~`). + * Code: Enclose the text with backticks (`` `code` ``). + + :::note Docusaurus Example + Bold: **Bold Text!**
+ Italic: *Italic Text*
+ Strikethrough: ~~Strikethrough Text~~
+ Code: `my code text` + ::: + +## Lists + +You can create both ordered and unordered lists: + +Unordered List: + +```markdown title="Markdown" +- Item 1 +- Item 2 + - Subitem 2.1 + - Subitem 2.2 +- Item 3 +``` + +Ordered List: +```markdown title="Markdown" +1. First item +2. Second item +3. Third item +``` + +:::note Docusaurus Example + +Unordered list: +- Item 1 +- Item 2 + - Subitem 2.1 + - Subitem 2.2 +- Item 3 + +Ordered list: +1. First item +2. Second item +3. Third item + +::: + +## Links + +You can add links in Markdown using square brackets and parentheses: + +```markdown title="Markdown" +[Link Text](https://www.example.com) +``` + +## Images + +You can include images using a similar syntax to links but with an exclamation mark at the beginning: + +``` +![Alt Text](image-url.jpg) +``` + +## Code Blocks + +To display code blocks, enclose the code within triple backticks: + +``````markdown +```js title="My Title" +console.log("Hello, Markdown!"); +``` +`````` + +:::note Docusaurus Example +```js title="My Title" +console.log("Hello, Markdown!"); +``` +::: + +## Tables + +Tables are created using vertical bars and hyphens: + +```markdown title="Markdown" +| Column 1 | Column 2 | +|----------|----------| +| Cell 1 | Cell 2 | +``` + +If you're finding this syntax difficult, you try using an online markdown table generator [here](https://tablesgenerator.com/markdown_tables). + +:::note Docusaurus Example +| Column 1 | Column 2 | +|----------|----------| +| Cell 1 | Cell 2 | +::: + + +## Blockquotes + +To create blockquotes, use the greater than (>) symbol: + +```markdown title="Markdown" +> This is a blockquote. +``` + +Example: +> This is a blockquote. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam non augue quis ligula malesuada finibus. Fusce neque dolor, aliquet et ornare viverra, tempus vel sapien. Phasellus vitae commodo dolor. + +## Escaping Characters + +To escape special characters in Markdown, use a backslash (\\): + +```markdown title="Markdown" +\*This text is not in italics\* +``` + +:::note Docusaurus Example +\*This text is not in italics\* +::: diff --git a/docs/website/docs-ufosc/static-pages.md b/docs/website/docs-ufosc/static-pages.md new file mode 100644 index 0000000..15bf285 --- /dev/null +++ b/docs/website/docs-ufosc/static-pages.md @@ -0,0 +1,36 @@ +--- +title: Static Pages +description: OSC Docs Static Pages +sidebar_position: 6 +--- + +# Static Pages + +You can create static pages that are not part of a documentation sub-site by creating JavaScript or Markdown files in the project's `src/pages` directory. By default, you'll be able to navigate to said pages by visiting the `/` path of the website. + +To add the site to the website's topmost navigation bar, navigate to the `themeConfig` property in `docusaurus.config.js` and add the following: + +```js title="docusaurus.config.js" +navbar: { + title: 'OSC Docs', + logo: { + alt: 'OSC Logo', + src: 'img/logo.png' + }, + items: [ + // .... + { + to: 'docs/club', // Your subsite routeBasePath + label: 'Club Archive', // Label to appear on the navmenu. + position: 'left' + } + // ... + ] +} +``` + +:::tip + +The OSC Docs homepage is an example of a non-documentation static page. You may find its source code (in Markdown) in the project's `src/pages/index.md` path. + +::: diff --git a/docs/website/docs-ufosc/usage.md b/docs/website/docs-ufosc/usage.md new file mode 100644 index 0000000..29a5cad --- /dev/null +++ b/docs/website/docs-ufosc/usage.md @@ -0,0 +1,74 @@ +--- +title: Usage +description: OSC Docs Usage +sidebar_position: 3 +--- + +# Usage + +:::tip Local Installation Required + +This section requires a local installation of the project repository. For installation instructions, refer to the [Installation Guide](/docs/website/docs-ufosc/installation). + +::: + +## Running the Project + +Viewing local changes to the project requires launching a development server. This can be achieved by calling the following command on your terminal application: + +```bash +npm start +``` + +The command must be called from within the project's root directory. The program should automatically open the site's local URL on your browser. If not, it can be accessed by visiting [localhost:3000](http://localhost:3000). + +## Linting + +The lint command is a linter command for Node.js projects that allows you to automatically analyze your codebase and identify potential issues or style violations. Linters are tools that enforce coding standards and best practices, helping developers maintain a consistent and clean codebase. Running the linter is necessary prior to committing to the codebase. + +To list potential style errors, run: +```bash +npm run lint +``` + +To (try) to automatically fix style errors, run: +```bash +npm run fix +``` + +Please note that if the `fix` command returns errors, they'll have to be manually resolved. + +## Building + +Docusaurus works by compiling Markdown files into static website files (HTML, CSS, JavaScript, etc.). If you're simply testing local changes, then the `npm start` command will suffice. However, it is not appropriate to use `npm start` in production environments. In order to host the site publicly, it must first be packaged and built. This is made possible with the build command: +```bash +npm run build +``` + +Then, the `serve` command (see [Serving Locally](/docs/website/docs-ufosc/usage#serving-locally)) may be used to test the site before releasing it to the public. + +## Serving Locally + +The serve command may be used to test generated site files prior to releasing the site to the public. It exists as a final test before releases, and is not suitable for hosting on production environments. Nonetheless, it can be invoked by the following command: + +```bash +npm run serve +``` + +## Deploying to GitHub Pages + +The `deploy` command is used for deploying to GitHub pages. See the [Docusaurus site](https://docusaurus.io/docs/deployment) for documentation. + +## Clearing Build Files + +The `clear` command deletes automatically generated files (including build files). It can be invoked by running the following: +```bash +npm run clear +``` + +## Docusaurus + +The `docusaurus` invokes the native Docusaurus command, displaying version info and usage instructions for internal commands. It may be invoked by running the following: +```bash +npm run docusaurus +``` diff --git a/docs/website/docs-ufosc/writingdocs.md b/docs/website/docs-ufosc/writingdocs.md new file mode 100644 index 0000000..f3656f4 --- /dev/null +++ b/docs/website/docs-ufosc/writingdocs.md @@ -0,0 +1,173 @@ +--- +title: Documentation +description: OSC Docs Writing Documentation +sidebar_position: 5 +--- + +# Writing Documentation + +Docusaurus is a powerful tool for creating documentation websites with ease. It simplifies the process of creating, organizing, and publishing documentation using Markdown as the primary content format. Markdown is a lightweight markup language that allows you to write formatted text, you can read more about it at the [Markdown Guide](/docs/website/docs-ufosc/markdown) page. + + +:::caution Installing the Project + +It is highly recommended to have the OSC Docs repository installed on your system prior to modifying the code base. Installation of OSC Docs is documented in the [Installation](/docs/website/docs-ufosc/installation) guide. + +::: + +## Documentation Site Structure + +Unlike most Docusaurus sites, which host documentation for a single project, the OSC Docs website organizes multiple projects into separate documentation sites (henceforth referred to as "sub-sites"). Each documentation sub-site resides in the project's 'docs' directory. In each sub-site's folder, a series of sub-folders and markdown files are stored. Docusaurus parses their structure and generates documentation sites automatically. + +### Pages + +Each file in a sub-site's folder will generate a separate documentation page. If there are multiple files in one folder, they will appear in alphabetical order + + + + + +:::tip + +Each file in the documentation directory appears as an entry (in alphabetical order) in the sub-site's navigation bar. If an 'index.md' file is added, then that'll be the first page visitors see when they navigate to the sub-site. + +::: + +### Folders + +Similarly, you can create sub-folders to your documentation sub-site. Creating a folder in the sub-site directory and adding at least one file to it will create a dropdown menu in the sub-site's navigation bar. + + + + +:::caution + +Sometimes, you might need to stop & restart docusaurus for new folders to take effect. Also, make sure that at least 1 file has been added to the sub-folder. + +::: + +### Customizing Order & Titles + +If you wish to name a navigation menu page something other than its file name, you can add a metadata section to your markdown file, as in the example below: + +```markdown +--- +title: Introduction +description: OSC Docs Introduction +sidebar_position: 1 +--- +``` + +The `sidebar_position` key can also be used to rearrange the page's position in the navigation menu. + +To customize folders and sub-menus, a separate metadata file needs to be created within the folder. The file must be called `_category_.json`, and assume the structure below: + +```json +{ + "position": 3, + "label": "Developers", + "collapsible": true, + "collapsed": true, +} +``` + +## Writing Documentation + +Documentation is written in Markdown format. To learn about the basics of Markdown, see the [Markdown](/docs/website/docs-ufosc/markdown) guide. + +To modify existing documentation, navigate to your desired project's subsite directory, and open your desired markdown (.md) file. Alternatively, if you wish to add a new page, simply create a new file and write up its content with [Markdown](/docs/website/docs-ufosc/markdown). + +## Creating sub-sites + +If, instead of modifying or adding to the documentation of an existing project, you wish to create a separate documentation site for a different project, you can do so by modifying the `docusaurus.config.js` file. + +To add a new subsite, first make sure that you've created a subfolder for your project in the 'docs' directory. Then, navigate to the `plugins` section in `docusaurus.config.js` and append your desired information into the array: + +```js title="docusaurus.config.js" +{ + plugins: [ + [ + '@docusaurus/plugin-content-docs', + { + id: 'website', // a unique ID for your project + path: 'docs/website', // the path to your docs folder + routeBasePath: 'docs/website', // the path on the website's URL + editUrl: 'https://github.com/ufosc/osc-docs' + } + ], + ] +} +``` + +### Adding the subsite to the navigation bar + +To add your subsite to the website's navigation bar, navigate to the `themeConfig` property in `docusaurus.config.js` and add the following: + +```js title="docusaurus.config.js" +// themeConfig.navbar attribute. +navbar: { + title: 'OSC Docs', + logo: { + alt: 'OSC Logo', + src: 'img/logo.png' + }, + items: [ + // .... + { + to: 'docs/club', // Your subsite routeBasePath + label: 'Club Archive', // Label to appear on the navmenu. + position: 'left' + } + // ... + ] +} +``` +:::tip Flagship Projects Only +Since navigation bar space is limited, please consider adding only flagship projects (i.e popular or actively maintained projects). The purpose of the navigation bar is provide high-visibility, convenient access to documentation pages; project that aren't being actively used or maintained should should be removed when new project sub-sites are created. +::: + +### Adding the subsite to the footer +The site's footer has a section demarcated as "Projects" that tracks documentation subsites. It is an alternative to the navigation bar that can be used to expose lower-priority or less frequently used subsites. To add a subsite to the footer, navigate to the `themeConfig` property in `docusaurus.config.js` and add your label and path to the themeConfig.footer.links object: + +```js title="docusaurus.config.js" +// See the themeConfig.footer.links attribute. +footer: { + style: 'dark', + links: [{ + title: 'Projects', + items: [ + { + label: 'OSC Website', + to: '/docs/website' + }, + { + label: 'OSC Docs', // Subsite label + to: '/docs/osc-docs' // Subsite routeBasePath + }, + ] + }, + // ... +} +``` + +### Adding the subsite to the home page +The home page index should list all available projects, regardless of priority or intended visibility. All project subsites should be listed. To add a project to the index, navigate to the "Documentation Index" header in 'src/pages/index.md': + +```md title="src/pages/index.md" +## Documentation Index + +* [Club Archive](/docs/club): Archive of club presentations, notes, etc. +* [OSC Website](/docs/website): User & Developer Documentation for the [OSC website](https://ufosc.org). +* [OSC Docs](/docs/osc-docs): Developer Documentation for the OSC Docs website. +* [Swamp Scheduler](/docs/swamp-scheduler): Developer Documentation for the Swamp Scheduler web-app. +``` + +## Previewing your Changes Live + +Starting a docusaurus server will allow you to instantly preview your markdown changes on your browser. It can be started by navigating to your project's directory, opening a terminal, and typing in the following command: + +```bash +npm start +``` + +For more information, see the [Usage](/docs/website/docs-ufosc/usage) section. You must have the project and its dependencies installed, if you don't, then refer to the [Installation](/docs/website/docs-ufosc/installation) guide. diff --git a/docs/website/index.md b/docs/website/index.md index 499779a..2bf1f58 100644 --- a/docs/website/index.md +++ b/docs/website/index.md @@ -1,36 +1,25 @@ --- -title: Open Source Club Website -description: Club Website Introduction +title: Introduction +description: Introduction to the Open Source Club website sidebar_position: 1 --- - - -

-[Homepage](https://ufosc.org) | [Documentation](https://docs.ufosc.org/docs/osc-docs) | [Discord](https://discord.com/invite/Gsxej6u) +This page hosts the documentation for the Open Source Club's (OSC) websites. OSC currently maintains two separate websites, the [Landing site](/docs/website/ufosc/introduction) and [Documentation Site](/docs/website/docs-ufosc/introduction). The separation intends to optimize mutually-exclusive concerns: the landing site aims for maximal performance and accessibility, whereas the documentation site seeks developer convenience (particularly for non-technical contributors). -

+Both websites are live and may be accessed through [ufosc.org](https://ufosc.org) or [docs.ufosc.org](https://docs.ufosc.org). -![GitHub issues](https://img.shields.io/github/issues-raw/ufosc/Club_Website_2) -![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/ufosc/Club_Website_2/gatsby.yml?label=ghpages) -![GitHub package.json version](https://img.shields.io/github/package-json/v/ufosc/Club_Website_2) -![GitHub](https://img.shields.io/github/license/ufosc/Club_Website_2) - -Website for the UF Open Source Club. Started in the Fall semester 2022, this website is built and maintained by club members to serve as a hub of information for the club. +## Landing Site + -## What is the Open Source Club? -The Open Source Club (OSC) at the University of Florida is a community of makers who want to solve problems and improve our world through open source projects. The club was founded in the Spring of 2016 as an official student organization at UF. In 2017, OSC were founding members of the Mozilla Open Source Student Network. Join us at casual codings, where we work on open source projects, do homework, or just hang out. +The landing site is the main UF Open Source Club website. It serves as a general hub of information concerning the club's operations at the University of Florida. We originally intended to integrate the site with docusaurus (i.e. to make it part of the documentation site), but found the docusaurus framework too restrictive and opinionated for our users' needs. Instead, we rebuilt the site from scratch using the GatsbyJS framework, which enabled us to build beautiful interactive components, integrate our content management system with GraphQL, and perform on-the-fly optimizations for the best user experience. -## Maintainers -Maintained by the UF Open Source Club, can be contacted via [Discord](https://discord.gg/j9g5dqSVD8) +The landing site hosts information on current OSC projects, which we automatically generate into dedicated pages from project specification files. Similarly, it contains a news/blog page, where Markdown documents are statically compiled into articles. -Current Maintainers: -- Michail Zeipekki [zeim839](https://github.com/zeim839) -- Daniel Wildsmith [danielwildsmith](https://github.com/danielwildsmith) + * The Landing site may be accessed at [ufosc.org](https://ufosc.org). + * The documentation for the landing site is hosted [here](/docs/website/ufosc/introduction). -## Contributing -All contributions are welcome and appreciated, we're always looking for new ideas or improvements. If you're interested in helping, please see the GitHub issues page for tasks that need help. Alternatively, you may propose new ideas by opening new issues. Contributors should read the [contribution guidelines](https://github.com/ufosc/Club_Website_2/blob/main/CONTRIBUTING.md). +## Documentation Site +The documentation site hosts project documentation, meeting presentations/recordings, and programming resources. It is primarily used by current club members and project contributors for retrieving documents and project specifications. We use the Docusaurus framework because it makes it extremely easy to set up dedicated pages and to accommodate a great variety of different media. It also makes it *extremely* easy for non-technical contributors to set up project documentation. -## License -[AGPL-3.0-or-later](https://github.com/ufosc/Club_Website_2/blob/main/LICENSE)
-Copyright (C) 2024 Open Source Club + * The documentation site may be accessed at [docs.ufosc.org](https://docs.ufosc.org). + * The documentation for the documentation site is hosted [here](/docs/website/docs-ufosc/introduction). diff --git a/docs/website/ufosc/_category_.json b/docs/website/ufosc/_category_.json new file mode 100644 index 0000000..3218993 --- /dev/null +++ b/docs/website/ufosc/_category_.json @@ -0,0 +1,6 @@ +{ + "position": 2, + "label": "Landing Site", + "collapsible": true, + "collapsed": false, +} diff --git a/docs/website/building.md b/docs/website/ufosc/building.md similarity index 100% rename from docs/website/building.md rename to docs/website/ufosc/building.md diff --git a/docs/website/getting-started.md b/docs/website/ufosc/getting-started.md similarity index 87% rename from docs/website/getting-started.md rename to docs/website/ufosc/getting-started.md index f64c80c..221c070 100644 --- a/docs/website/getting-started.md +++ b/docs/website/ufosc/getting-started.md @@ -6,7 +6,7 @@ sidebar_position: 2 This post will help get your development environment set up such that you can develop, test, write blog/project content, or deploy the OSC website. -The project is built using the [GatsbyJS](https://www.gatsbyjs.com/) framework, which is a static site builder based on [ReactJS](https://react.dev/). You do not need to be familiar with either of these technologies to produce blog/project content, but getting a live environment set up where you can see your changes immediately reflected on the browser is extremely helpful. If you're interested in learning web-dev fundamentals, we recommend reading our [HTML](/docs/club/resources/html), [JavaScript](/docs/club/resources/javascript), and [CSS](/docs/club/resources/css) guides. +The project is built using the [GatsbyJS](https://www.gatsbyjs.com/) framework, which is a static site builder based on [ReactJS](https://react.dev/). You do not need to be familiar with either of these technologies to produce blog/project content, but getting a live environment set up where you can see your changes immediately reflected on the browser is extremely helpful. If you're interested in learning web-dev fundamentals, we recommend reading our [HTML](/docs/resources/html), [JavaScript](/docs/resources/javascript), and [CSS](/docs/resources/css) guides. ## Downloading the project @@ -18,6 +18,10 @@ cd Club_Website_2 ``` ## Installing NodeJS +:::warning Recommended NodeJS Release +We recommend the NodeJS v18 LTS release for best results. +::: + You will need to install [NodeJS](https://nodejs.org/en) to run the project. NodeJS is a JavaScript execution environment that allows you to run server-side JavaScript code. It is used to test, build, and deploy the project. ## Installing Dependencies @@ -26,7 +30,7 @@ Assuming you've installed NodeJS, you can install the project's dependencies wit npm install --force ``` -If you're unsure how to run commands on a console or terminal, we suggest reading our [Bash](/docs/club/resources/bash) guide. +If you're unsure how to run commands on a console or terminal, we suggest reading our [Bash](/docs/resources/bash) guide. ## Running the site At this point, you're ready to start a development server that hosts the website on your local machine. To get started, run the following command: diff --git a/docs/website/ufosc/introduction.md b/docs/website/ufosc/introduction.md new file mode 100644 index 0000000..8e863ca --- /dev/null +++ b/docs/website/ufosc/introduction.md @@ -0,0 +1,36 @@ +--- +title: Introduction +description: Club Website Introduction +sidebar_position: 1 +--- + + +

+ +[Homepage](https://ufosc.org) | [Documentation](/docs/website) | [Discord](https://discord.com/invite/Gsxej6u) + +

+ +![GitHub issues](https://img.shields.io/github/issues-raw/ufosc/Club_Website_2) +![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/ufosc/Club_Website_2/gatsby.yml?label=ghpages) +![GitHub package.json version](https://img.shields.io/github/package-json/v/ufosc/Club_Website_2) +![GitHub](https://img.shields.io/github/license/ufosc/Club_Website_2) + +Website for the UF Open Source Club. Started in the Fall semester 2022, this website is built and maintained by club members to serve as a hub of information for the club. + +## What is the Open Source Club? +The Open Source Club (OSC) at the University of Florida is a community of makers who want to solve problems and improve our world through open source projects. The club was founded in the Spring of 2016 as an official student organization at UF. In 2017, OSC were founding members of the Mozilla Open Source Student Network. Join us at casual codings, where we work on open source projects, do homework, or just hang out. + +## Maintainers +Maintained by the UF Open Source Club, can be contacted via [Discord](https://discord.gg/j9g5dqSVD8) + +Current Maintainers: +- Michail Zeipekki [zeim839](https://github.com/zeim839) +- Daniel Wildsmith [danielwildsmith](https://github.com/danielwildsmith) + +## Contributing +All contributions are welcome and appreciated, we're always looking for new ideas or improvements. If you're interested in helping, please see the GitHub issues page for tasks that need help. Alternatively, you may propose new ideas by opening new issues. Contributors should read the [contribution guidelines](https://github.com/ufosc/Club_Website_2/blob/main/CONTRIBUTING.md). + +## License +[AGPL-3.0-or-later](https://github.com/ufosc/Club_Website_2/blob/main/LICENSE)
+Copyright (C) 2024 Open Source Club diff --git a/docs/website/legacy/Developers/API/_category_.json b/docs/website/ufosc/legacy/Developers/API/_category_.json similarity index 100% rename from docs/website/legacy/Developers/API/_category_.json rename to docs/website/ufosc/legacy/Developers/API/_category_.json diff --git a/docs/website/legacy/Developers/API/api.md b/docs/website/ufosc/legacy/Developers/API/api.md similarity index 91% rename from docs/website/legacy/Developers/API/api.md rename to docs/website/ufosc/legacy/Developers/API/api.md index d1e05c3..15bad81 100644 --- a/docs/website/legacy/Developers/API/api.md +++ b/docs/website/ufosc/legacy/Developers/API/api.md @@ -11,10 +11,10 @@ This page is part of the documentation for release V1.0. This documentation is o ::: The OSC website API exists to serve, create, modify, and delete dynamic resources, for instance: -1. Blog metadata and rendered HTML articles (documented in [Developers/API/blog](/docs/website/legacy/Developers/API/blog)). -2. Passing contact messages to the SMTP mail server (documented in [Developers/API/contact](/docs/website/legacy/Developers/API/contact)). -3. Serving the various editable forms (documented in [Developers/API/edit](/docs/website/legacy/Developers/API/edit)). -4. User authentication (documented in [Developers/API/users](/docs/website/legacy/Developers/API/users)). +1. Blog metadata and rendered HTML articles (documented in [Developers/API/blog](/docs/website/ufosc/legacy/Developers/API/blog)). +2. Passing contact messages to the SMTP mail server (documented in [Developers/API/contact](/docs/website/ufosc/legacy/Developers/API/contact)). +3. Serving the various editable forms (documented in [Developers/API/edit](/docs/website/ufosc/legacy/Developers/API/edit)). +4. User authentication (documented in [Developers/API/users](/docs/website/ufosc/legacy/Developers/API/users)). In the source code, each route occupies a separate file in the [routes folder](https://github.com/ufosc/Club_Website_2/tree/main/routes), and all routes are subsequently organized in [routes/api.js](https://github.com/ufosc/Club_Website_2/blob/main/routes/api.js). diff --git a/docs/website/legacy/Developers/API/blog.md b/docs/website/ufosc/legacy/Developers/API/blog.md similarity index 98% rename from docs/website/legacy/Developers/API/blog.md rename to docs/website/ufosc/legacy/Developers/API/blog.md index 340212f..ad0c139 100644 --- a/docs/website/legacy/Developers/API/blog.md +++ b/docs/website/ufosc/legacy/Developers/API/blog.md @@ -10,7 +10,7 @@ sidebar_position: 2 This page is part of the documentation for release V1.0. This documentation is outdated and V1.0 is no longer maintained. See [index](/docs/website/) for the latest information. ::: -The blog route interfaces with the blog [database model](/docs/website/legacy/Developers/Databases/models) and dynamically renders blog articles. +The blog route interfaces with the blog [database model](/docs/website/ufosc/legacy/Developers/Databases/models) and dynamically renders blog articles. :::tip routes/blog.js @@ -66,7 +66,7 @@ curl -XGET 'https://ufosc.org/api/blog' This route fetches articles by the specified URL ID parameter and returns them as rendered HTML. An error article is rendered if the ID is invalid or non-existent. -Articles whose status is not 'published' (e.g 'draft') are only visible to authenticated users. They do not render on the /blog page, but may be accessed by authenticated users if their ID is known. Generally, authenticated users may access these posts by clicking on the 'preview' button alongside their table entries in the [admin dashboard](/docs/website/legacy/admin). +Articles whose status is not 'published' (e.g 'draft') are only visible to authenticated users. They do not render on the /blog page, but may be accessed by authenticated users if their ID is known. Generally, authenticated users may access these posts by clicking on the 'preview' button alongside their table entries in the [admin dashboard](/docs/website/ufosc/legacy/admin). ### Request Parameters diff --git a/docs/website/legacy/Developers/API/contact.md b/docs/website/ufosc/legacy/Developers/API/contact.md similarity index 94% rename from docs/website/legacy/Developers/API/contact.md rename to docs/website/ufosc/legacy/Developers/API/contact.md index 36ec43a..db8b731 100644 --- a/docs/website/legacy/Developers/API/contact.md +++ b/docs/website/ufosc/legacy/Developers/API/contact.md @@ -22,7 +22,7 @@ The contact route is defined in [/routes/contact.js](https://github.com/ufosc/Cl This route expects the contact form's field data (as JSON). If the data is successfully validated, it sends an email to the admin account notifying it of the new message, whilst also sending a receipt of the submitted form to the specified email address of the submitter. -Email protocol interfacing is achieved via an SMTP server, which receives and processes outgoing server mail. For configuration instructions, see [configuration](/docs/website/legacy/Developers/configuration). +Email protocol interfacing is achieved via an SMTP server, which receives and processes outgoing server mail. For configuration instructions, see [configuration](/docs/website/ufosc/legacy/Developers/configuration). ### Request Parameters diff --git a/docs/website/legacy/Developers/API/edit.md b/docs/website/ufosc/legacy/Developers/API/edit.md similarity index 100% rename from docs/website/legacy/Developers/API/edit.md rename to docs/website/ufosc/legacy/Developers/API/edit.md diff --git a/docs/website/legacy/Developers/API/users.md b/docs/website/ufosc/legacy/Developers/API/users.md similarity index 98% rename from docs/website/legacy/Developers/API/users.md rename to docs/website/ufosc/legacy/Developers/API/users.md index 4e62bde..7154e99 100644 --- a/docs/website/legacy/Developers/API/users.md +++ b/docs/website/ufosc/legacy/Developers/API/users.md @@ -10,7 +10,7 @@ sidebar_position: 6 This page is part of the documentation for release V1.0. This documentation is outdated and V1.0 is no longer maintained. See [index](/docs/website/) for the latest information. ::: -The users route interfaces with the users [database model](/docs/website/legacy/Developers/Databases/models) and serves users using their database ID. +The users route interfaces with the users [database model](/docs/website/ufosc/legacy/Developers/Databases/models) and serves users using their database ID. :::tip routes/users.js diff --git a/docs/website/legacy/Developers/Databases/_category_.json b/docs/website/ufosc/legacy/Developers/Databases/_category_.json similarity index 100% rename from docs/website/legacy/Developers/Databases/_category_.json rename to docs/website/ufosc/legacy/Developers/Databases/_category_.json diff --git a/docs/website/legacy/Developers/Databases/models.md b/docs/website/ufosc/legacy/Developers/Databases/models.md similarity index 86% rename from docs/website/legacy/Developers/Databases/models.md rename to docs/website/ufosc/legacy/Developers/Databases/models.md index 6b3503b..37539d8 100644 --- a/docs/website/legacy/Developers/Databases/models.md +++ b/docs/website/ufosc/legacy/Developers/Databases/models.md @@ -16,7 +16,7 @@ The database's structure is defined by the following collections: :::note -To learn more about using models with MongooseJS, see [Using MongoDB](/docs/website/legacy/Developers/Databases/mongodb). +To learn more about using models with MongooseJS, see [Using MongoDB](/docs/website/ufosc/legacy/Developers/Databases/mongodb). ::: @@ -24,4 +24,4 @@ Model instances are created and saved to the database in each model's correspond * Blog posts are managed in [routes/blog.js](https://github.com/ufosc/Club_Website_2/blob/main/routes/blog.js). * Users are managed in [routes/users.js](https://github.com/ufosc/Club_Website_2/blob/main/routes/users.js). -To learn more about routes, see [API & Routes](/docs/website/legacy/Developers/API/). +To learn more about routes, see [API & Routes](/docs/website/ufosc/legacy/Developers/API). diff --git a/docs/website/legacy/Developers/Databases/mongodb.md b/docs/website/ufosc/legacy/Developers/Databases/mongodb.md similarity index 98% rename from docs/website/legacy/Developers/Databases/mongodb.md rename to docs/website/ufosc/legacy/Developers/Databases/mongodb.md index 5101aa6..eb65e66 100644 --- a/docs/website/legacy/Developers/Databases/mongodb.md +++ b/docs/website/ufosc/legacy/Developers/Databases/mongodb.md @@ -12,7 +12,7 @@ This page is part of the documentation for release V1.0. This documentation is o The website uses [MongoDB](https://www.mongodb.com/), a document-oriented database program, to fetch and serve information for the backend. When running in a development environment, the backend is automatically configured to connect to a public OSC testing database. This section documents the basic prolegomena of operating and managing the OSC Website database. -For the OSC testing URI, see [here](https://github.com/ufosc/Club_Website_2/blob/main/utils/config.js#L3) (note that the database is public and volatile, and not meant for production environments). For instructions on changing environments or configuring your own Mongo connection URI, see [here](/docs/website/legacy/Developers/configuration). +For the OSC testing URI, see [here](https://github.com/ufosc/Club_Website_2/blob/main/utils/config.js#L3) (note that the database is public and volatile, and not meant for production environments). For instructions on changing environments or configuring your own Mongo connection URI, see [here](/docs/website/ufosc/legacy/Developers/configuration). ## Mongoose Basics diff --git a/docs/website/legacy/Developers/_category_.json b/docs/website/ufosc/legacy/Developers/_category_.json similarity index 100% rename from docs/website/legacy/Developers/_category_.json rename to docs/website/ufosc/legacy/Developers/_category_.json diff --git a/docs/website/legacy/Developers/authentication.md b/docs/website/ufosc/legacy/Developers/authentication.md similarity index 100% rename from docs/website/legacy/Developers/authentication.md rename to docs/website/ufosc/legacy/Developers/authentication.md diff --git a/docs/website/legacy/Developers/caching.md b/docs/website/ufosc/legacy/Developers/caching.md similarity index 95% rename from docs/website/legacy/Developers/caching.md rename to docs/website/ufosc/legacy/Developers/caching.md index 75a3537..0894467 100644 --- a/docs/website/legacy/Developers/caching.md +++ b/docs/website/ufosc/legacy/Developers/caching.md @@ -10,7 +10,7 @@ sidebar_position: 6 This page is part of the documentation for release V1.0. This documentation is outdated and V1.0 is no longer maintained. See [index](/docs/website/) for the latest information. ::: -Caching allows the website's server to improve performance and preserve CPU by storing time-insensitive data in memory. Its most common use case is in serving the home and blog pages: instead of dynamically re-rendering the same page for each user request, it is rendered only once and then served from memory. Naturally, the cache updates its data after some predetermined time period, configurable by the [CACHE_INTERVAL](/docs/website/legacy/Developers/configuration#caching) environment variable. +Caching allows the website's server to improve performance and preserve CPU by storing time-insensitive data in memory. Its most common use case is in serving the home and blog pages: instead of dynamically re-rendering the same page for each user request, it is rendered only once and then served from memory. Naturally, the cache updates its data after some predetermined time period, configurable by the [CACHE_INTERVAL](/docs/website/ufosc/legacy/Developers/configuration#caching) environment variable. ## Cache Module diff --git a/docs/website/legacy/Developers/configuration.md b/docs/website/ufosc/legacy/Developers/configuration.md similarity index 100% rename from docs/website/legacy/Developers/configuration.md rename to docs/website/ufosc/legacy/Developers/configuration.md diff --git a/docs/website/legacy/Developers/contributing-guide.md b/docs/website/ufosc/legacy/Developers/contributing-guide.md similarity index 100% rename from docs/website/legacy/Developers/contributing-guide.md rename to docs/website/ufosc/legacy/Developers/contributing-guide.md diff --git a/docs/website/legacy/Developers/introduction.md b/docs/website/ufosc/legacy/Developers/introduction.md similarity index 100% rename from docs/website/legacy/Developers/introduction.md rename to docs/website/ufosc/legacy/Developers/introduction.md diff --git a/docs/website/legacy/Developers/kubernetes.md b/docs/website/ufosc/legacy/Developers/kubernetes.md similarity index 96% rename from docs/website/legacy/Developers/kubernetes.md rename to docs/website/ufosc/legacy/Developers/kubernetes.md index e280b2e..f7c40a4 100644 --- a/docs/website/legacy/Developers/kubernetes.md +++ b/docs/website/ufosc/legacy/Developers/kubernetes.md @@ -15,7 +15,7 @@ Kubernetes, often abbreviated as K8s, is an open-source container orchestration Kubernetes is based on Docker, an open-source platform and a set of tools for creating, deploying, and managing containerized applications. To deploy the website on Kubernetes, you'll first need to build the website's container image. ## Prerequisites -1. Complete the [Getting Started](/docs/website/legacy/Developers/introduction) guide. +1. Complete the [Getting Started](/docs/website/ufosc/legacy/Developers/introduction) guide. 2. [Docker](https://www.docker.com/): build the website container image. 3. Kubernetes Cluster & Kubectl: Use a cloud hosting platform or [launch a Kubernetes node on Docker](https://docs.docker.com/desktop/kubernetes/). @@ -257,7 +257,7 @@ See Google's documentation [here](https://cloud.google.com/load-balancing/docs/u ## Creating an Admin -The Kubernetes config sets up the website with an empty database, which makes logging in to the site is impossible. This is solved by connecting to the Mongo container and calling mongosh to add the first user. This process should only be done once, additional admins can be added through the [admin dashboard](/docs/website/legacy/admin). +The Kubernetes config sets up the website with an empty database, which makes logging in to the site is impossible. This is solved by connecting to the Mongo container and calling mongosh to add the first user. This process should only be done once, additional admins can be added through the [admin dashboard](/docs/website/ufosc/legacy/admin). First, get a list of all pods ```bash @@ -286,6 +286,6 @@ use test db.users.insertOne({"username": "admin","password": {"hash": "�a2O���w��\u0004��Ȳ��7\u000fM�2\u0011�<\u0015z\u0016\u0019E*��cЮ\u0010\u001e\u0015���ւ)�Ne��G�VH/��9�����q\u0003�\t��פ}���i��Y�\u00125��d3�V�\t6������W;�~���?A��\u001c��X8��/\u0012��\u0007)t��9\u0001<","salt": "4vRF0ZTMELWmPGMpAgy6hsiJm/pOUlgPYFk+faK+yaFv/x0+lITG+4kX/y5bXudjMdGWLN2PV8UhH5s5dRLPaGgh2qwrbocDqEdyvbqSqVPAQxKIwFSytoRySYfKZJdCgK970UmrPDyGmoAIRZ/DN8YZ4fTirkSAeRlTWLSbyfg="},"fullName": "admin","role": "admin","isAdmin": true,"date": {"$date": "2023-09-17T15:53:18.529Z"},"__v": 0}) ``` -The command above adds a user with the username `admin` and password `123456`. You should now reset the admin's password using the [admin dashboard](/docs/website/legacy/admin) as soon as possible to prevent attackers from logging in with the default credentials. Resetting the password through the admin dashboard should reset the password salt as well. +The command above adds a user with the username `admin` and password `123456`. You should now reset the admin's password using the [admin dashboard](/docs/website/ufosc/legacy/admin) as soon as possible to prevent attackers from logging in with the default credentials. Resetting the password through the admin dashboard should reset the password salt as well. Finally, type `exit` and press enter to exit the mongosh console. Type `exit` and press enter once again to close the connection to the pod. diff --git a/docs/website/legacy/Developers/rendering.md b/docs/website/ufosc/legacy/Developers/rendering.md similarity index 100% rename from docs/website/legacy/Developers/rendering.md rename to docs/website/ufosc/legacy/Developers/rendering.md diff --git a/docs/website/legacy/Developers/testing.md b/docs/website/ufosc/legacy/Developers/testing.md similarity index 87% rename from docs/website/legacy/Developers/testing.md rename to docs/website/ufosc/legacy/Developers/testing.md index 4de858e..bb8d22d 100644 --- a/docs/website/legacy/Developers/testing.md +++ b/docs/website/ufosc/legacy/Developers/testing.md @@ -18,15 +18,15 @@ Any contribution to the OSC Website source code must pass testing and linting wo Source code and documentation indices for currently available unit tests. - * Blog API Route Tests: [GitHub](https://github.com/ufosc/Club_Website_2/blob/main/test/blog.spec.js) or [Docs](/docs/website/legacy/Developers/API/blog). - * Cache Tests: [GitHub](https://github.com/ufosc/Club_Website_2/blob/main/test/cache.spec.js) or [Docs](/docs/website/legacy/Developers/caching). - * Edit API Route Tests: [GitHub](https://github.com/ufosc/Club_Website_2/blob/main/test/edit.spec.js) or [Docs](/docs/website/legacy/Developers/API/edit). - * Users API Route Tests: [GitHub](https://github.com/ufosc/Club_Website_2/blob/main/test/users.spec.js) or [Docs](/docs/website/legacy/Developers/API/users). + * Blog API Route Tests: [GitHub](https://github.com/ufosc/Club_Website_2/blob/main/test/blog.spec.js) or [Docs](/docs/website/ufosc/legacy/Developers/API/blog). + * Cache Tests: [GitHub](https://github.com/ufosc/Club_Website_2/blob/main/test/cache.spec.js) or [Docs](/docs/website/ufosc/legacy/Developers/caching). + * Edit API Route Tests: [GitHub](https://github.com/ufosc/Club_Website_2/blob/main/test/edit.spec.js) or [Docs](/docs/website/ufosc/legacy/Developers/API/edit). + * Users API Route Tests: [GitHub](https://github.com/ufosc/Club_Website_2/blob/main/test/users.spec.js) or [Docs](/docs/website/ufosc/legacy/Developers/API/users). ## Running Tests :::danger -Tests are only meant to be ran on development environments. Do not use production databases in testing, their contents risk being deleted. To learn more about managing environments, see [Usage & Configuration](/docs/website/legacy/Developers/configuration). +Tests are only meant to be ran on development environments. Do not use production databases in testing, their contents risk being deleted. To learn more about managing environments, see [Usage & Configuration](/docs/website/ufosc/legacy/Developers/configuration). ::: diff --git a/docs/website/legacy/_category_.json b/docs/website/ufosc/legacy/_category_.json similarity index 100% rename from docs/website/legacy/_category_.json rename to docs/website/ufosc/legacy/_category_.json diff --git a/docs/website/legacy/admin.md b/docs/website/ufosc/legacy/admin.md similarity index 98% rename from docs/website/legacy/admin.md rename to docs/website/ufosc/legacy/admin.md index 7078b1b..f2f9e00 100644 --- a/docs/website/legacy/admin.md +++ b/docs/website/ufosc/legacy/admin.md @@ -10,7 +10,7 @@ This page is part of the documentation for release V1.0. This documentation is o # Admin Dashboard -The OSC website implements a minimal content management system for managing site users, blog posts, and images. This section of the documentation is intended as a users guide. For developer documentation see the [developer guide](/docs/website/legacy/Developers/introduction). +The OSC website implements a minimal content management system for managing site users, blog posts, and images. This section of the documentation is intended as a users guide. For developer documentation see the [developer guide](/docs/website/ufosc/legacy/Developers/introduction). ## Getting Started :::info diff --git a/docs/website/legacy/api-reference.md b/docs/website/ufosc/legacy/api-reference.md similarity index 95% rename from docs/website/legacy/api-reference.md rename to docs/website/ufosc/legacy/api-reference.md index ca7ee7d..25304ce 100644 --- a/docs/website/legacy/api-reference.md +++ b/docs/website/ufosc/legacy/api-reference.md @@ -15,7 +15,7 @@ Routes are currently limited to 100-500 (may vary) requests per minute. ::: :::note -The OSC Website API is intended for internal use only. Only non-authenticated public routes have been documented here. If you're seeking documentation for a self-hosted instance, refer to the [developers guide](/docs/website/legacy/Developers/API/) instead. +The OSC Website API is intended for internal use only. Only non-authenticated public routes have been documented here. If you're seeking documentation for a self-hosted instance, refer to the [developers guide](/docs/website/ufosc/legacy/Developers/API) instead. ::: @@ -67,7 +67,7 @@ curl -XGET 'https://ufosc.org/api/blog' This route fetches articles by the specified URL ID parameter and returns them as rendered HTML. An error article is rendered if the ID is invalid or non-existent. -Articles whose status is not 'published' (e.g 'draft') are only visible to authenticated users. They do not render on the /blog page, but may be accessed by authenticated users if their ID is known. Generally, authenticated users may access these posts by clicking on the 'preview' button alongside their table entries in the [admin dashboard](/docs/website/legacy/admin). +Articles whose status is not 'published' (e.g 'draft') are only visible to authenticated users. They do not render on the /blog page, but may be accessed by authenticated users if their ID is known. Generally, authenticated users may access these posts by clicking on the 'preview' button alongside their table entries in the [admin dashboard](/docs/website/ufosc/legacy/admin). ### Request Parameters diff --git a/docs/website/legacy/index.md b/docs/website/ufosc/legacy/index.md similarity index 77% rename from docs/website/legacy/index.md rename to docs/website/ufosc/legacy/index.md index 0730ea6..8f7c77c 100644 --- a/docs/website/legacy/index.md +++ b/docs/website/ufosc/legacy/index.md @@ -13,9 +13,9 @@ This page is part of the documentation for release V1.0. This documentation is o This page hosts user and developer documentation for the official [OSC Website](https://ufosc.org). - * [Admin Dashboard](/docs/website/legacy/admin): User guide to using the website's built-in content management system. - * [Developers](/docs/website/legacy/Developers/introduction): Developer documentation for contributing/modifying the OSC website. - * [API Reference](/docs/website/legacy/api-reference): Reference of the site's public API. + * [Admin Dashboard](/docs/website/ufosc/legacy/admin): User guide to using the website's built-in content management system. + * [Developers](/docs/website/ufosc/legacy/Developers/introduction): Developer documentation for contributing/modifying the OSC website. + * [API Reference](/docs/website/ufosc/legacy/api-reference): Reference of the site's public API. You may find the project's source on [Github](https://github.com/ufosc/Club_Website_2) (subject to the [AGLP-3.0-or-later license](https://github.com/ufosc/Club_Website_2/blob/main/LICENSE.md)). diff --git a/docs/website/publishing-news.md b/docs/website/ufosc/publishing-news.md similarity index 97% rename from docs/website/publishing-news.md rename to docs/website/ufosc/publishing-news.md index beabfd2..5c76463 100644 --- a/docs/website/publishing-news.md +++ b/docs/website/ufosc/publishing-news.md @@ -6,7 +6,7 @@ sidebar_position: 4 # Publishing News -News can be published by creating markdown files in the `/src/content/` directory. Markdown is a markup language for writing on the web, it is explained in the [Markdown guide](/docs/osc-docs/markdown). +News can be published by creating markdown files in the `/src/content/` directory. Markdown is a markup language for writing on the web, it is explained in the [Markdown guide](/docs/website/docs-ufosc/markdown). :::tip To preview your article as it will appear on the website and see updates in real-time as you make changes, ensure that the development server is running by executing the command `npm run develop`.