Updated documentation
This commit is contained in:
Prozilla
parent
0eeb87cd7b
commit
059c2e6835
8 changed files with 159 additions and 95 deletions
7
.vscode/extensions.json
vendored
Normal file
7
.vscode/extensions.json
vendored
Normal file
|
|
@ -0,0 +1,7 @@
|
|||
{
|
||||
"recommendations": [
|
||||
"bierner.github-markdown-preview",
|
||||
"yahyabatulu.vscode-markdown-alert",
|
||||
"clinyong.vscode-css-modules"
|
||||
]
|
||||
}
|
||||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
# Documentation
|
||||
|
||||
## Table of Contents
|
||||
## Pages
|
||||
|
||||
- [Features](features/README.md)
|
||||
- [Configuration](configuration/README.md)
|
||||
|
|
@ -19,39 +19,49 @@
|
|||
2. Run `npm install` to install dependencies.
|
||||
3. Run `npm start` to start the web server and go to [localhost:3000](http://localhost:3000/).
|
||||
|
||||
### Development
|
||||
### How to run
|
||||
|
||||
1. Run `npm start` and watch your changes live at [localhost:3000](http://localhost:3000/).
|
||||
2. Vite's hot module replacement makes sure your changes applied without needing to refresh the website.
|
||||
These are the scripts in logical order, that will be available when you have installed the dependencies. Note that certain scripts can be omitted by running another script. For more information about scripts #1, #2 and #3, check the [officiel Vite documentation](https://vitejs.dev/guide/cli.html).
|
||||
|
||||
### Building & deploying
|
||||
1. `npm run start`
|
||||
|
||||
1. Run `npm run build`, which will bundle all your files in the `dist` directory.
|
||||
2. Upload the contents of the `dist` directory to your web server's root folder.
|
||||
Start Vite dev server at [localhost:3000](http://localhost:3000/). Changes to module will dynamically be hot-reloaded, so normally there is no need for hard-refreshes.
|
||||
|
||||
#### Deploying to GitHub Pages
|
||||
2. `npm run build`
|
||||
|
||||
1. Open [deploy.sh](../deploy.sh) and change `DOMAIN` to your domain, `COMMIT_MESSAGE` to your commit message and `REPO_URL` to the URL of your repo. Make sure you don't accidentally add or remove any quotes when editing these values.
|
||||
2. Run `npm run deploy` - This will create a new build by running the redeploy script, add a CNAME pointing to your domain and then push the build folder to a branch called `gh-pages`.
|
||||
3. Configure your GitHub Pages to deploy the `gh-pages` branch to your domain.
|
||||
Compile project using TypeScript and bundle all files into the `dist` directory. This directory can be uploaded to a web server.
|
||||
|
||||
Once the initial setup is complete, you can simply run `npm run deploy` and your website will be built and deployed to GitHub Pages.
|
||||
3. `npm run serve`
|
||||
|
||||
> Note: When the deployment process is complete, you won't see the changes reflected on your website until a few moments later. This is because GitHub Pages needs to run its own build step before the website updates. You can view details about this process in the `Actions` tab on GitHub.
|
||||
Start web server with preview of build at [localhost:8080](http://localhost:8080/). Can be useful for testing build before deploying.
|
||||
|
||||
4. `npm run stage`
|
||||
|
||||
Run [node program](../src/tools/stage.ts) that stages the build and prepares it for deployment. Script will generate a sitemap, CNAME file, etc.
|
||||
|
||||
5. `npm run deploy`
|
||||
|
||||
Run scripts #2 and #4, then execute [deploy.sh](../deploy.sh), which deploys the staged build to GitHub Pages on branch called `gh-pages`.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> Check the "Deployment" section on the [Configuration](./configuration/README.md) page, to see what configurations must be made before starting the staging or deployment process.
|
||||
|
||||
> [!NOTE]
|
||||
> After this deployment process, GitHub Pages will run its own build step to finalize the deployment, as seen in the `Actions` tab on GitHub. This usually takes less than a minute and once it's done, your deployment will be live.
|
||||
|
||||
### Configuration
|
||||
|
||||
See [docs/configuration](configuration/README.md) for more information.
|
||||
|
||||
### Structure
|
||||
### Project structure
|
||||
|
||||
- [src](../src) directory
|
||||
|
||||
Contains all code for the application, including CSS, JS and HTML files. This directory makes use of a feature-based folder structure. Utility files are often separated into their own subdirectory, called `_utils`, inside of their respective directory.
|
||||
Contains all code for the application, including HTML, CSS and TypeScript files. This directory makes use of a feature-based folder structure. Utility files are often separated into their own subdirectory, called `_utils`, inside of their respective directory.
|
||||
|
||||
- [public](../public) directory
|
||||
|
||||
Contains all static files like images, webfonts and vector graphics as well as the [index.html](../public/index.html) file, which contains all metadata and contains all bundled scripts after the build step. Also includes the [config](../public/config) and [documents](../public/documents) folders from where certain files are loaded into the [virtual drive](features/virtual-drive/README.md).
|
||||
Contains all static files like images, webfonts and vector graphics. Also includes the [config](../public/config) and [documents](../public/documents) folders from where certain files are loaded into the [virtual drive](features/virtual-drive/README.md).
|
||||
|
||||
- [docs](.) directory
|
||||
|
||||
|
|
@ -59,27 +69,26 @@ See [docs/configuration](configuration/README.md) for more information.
|
|||
|
||||
- [dist](../dist) directory
|
||||
|
||||
Contains the static build files after [building](#building--deploying) the application. This directory is not included in the GitHub repository.
|
||||
Contains the bundled build after the build process. This directory is not included in the GitHub repository.
|
||||
|
||||
- External files
|
||||
- [Design file (Figma)](https://www.figma.com/file/bEE5RyWgV0QILcXpZWEk2r/ProzillaOS?type=design&node-id=0%3A1&mode=design&t=7KR1tKCp9H5cK3hf-1)
|
||||
- [Task board (Notion)](https://prozilla.notion.site/8325fabca1fb4f9885b6d6dfd5aa64c8?v=1a59f7ce50914f5ea711fe6460e52868&pvs=4)
|
||||
|
||||
### Code style
|
||||
|
||||
Type | Case | Example
|
||||
--- | --- | ---
|
||||
Folders | kebab-case | `virtual-drive`
|
||||
`.ts` files | camelCase | `virtualRoot.ts`
|
||||
`.tsx` files | PascalCase | `Desktop.tsx`
|
||||
`.css` files & static assets | kebab-case | `global.css`
|
||||
Local `.module.css` files | PascalCase | `Desktop.module.css`
|
||||
Global `.module.css` files | kebab-case | `utils.module.css`
|
||||
CSS class names | PascalCase | ```.WindowsView```
|
||||
Variables | camelCase | ```const fooBar = true;```
|
||||
Global constant variables | MACRO_CASE | ```export const NAME = "ProzillaOS";```
|
||||
Classes | PascalCase | ```class WindowsManager { }```
|
||||
React components | PascalCase | ```export function WindowsView({ }) { }```
|
||||
Functions | camelCase | ```function focusWindow() { }```
|
||||
Types | PascalCase | ```type FooBar = boolean;```
|
||||
|
||||
### External files
|
||||
|
||||
- [Design file (Figma)](https://www.figma.com/file/bEE5RyWgV0QILcXpZWEk2r/ProzillaOS?type=design&node-id=0%3A1&mode=design&t=7KR1tKCp9H5cK3hf-1)
|
||||
- [Task board (Notion)](https://prozilla.notion.site/8325fabca1fb4f9885b6d6dfd5aa64c8?v=1a59f7ce50914f5ea711fe6460e52868&pvs=4)
|
||||
Type | Case | Example | Based on
|
||||
--- | --- | --- | ---
|
||||
Folders | kebab-case | `virtual-drive` |
|
||||
`.ts` files | camelCase | `virtualRoot.ts` |
|
||||
`.tsx` files | PascalCase | `Desktop.tsx` | React component
|
||||
`.css` files & static assets | kebab-case | `global.css` |
|
||||
Local `.module.css` files | PascalCase | `Desktop.module.css` | React component
|
||||
Global `.module.css` files | kebab-case | `utils.module.css` |
|
||||
CSS class names | PascalCase | ```.WindowsView``` | React component
|
||||
Variables | camelCase | ```const fooBar = true;``` |
|
||||
Global constant variables | MACRO_CASE | ```export const NAME = "ProzillaOS";``` |
|
||||
Classes | PascalCase | ```class WindowsManager { }``` |
|
||||
React components | PascalCase | ```export function WindowsView({ }) { }``` |
|
||||
Functions | camelCase | ```function focusWindow() { }``` |
|
||||
Types | PascalCase | ```type FooBar = boolean;``` |
|
||||
|
|
@ -2,10 +2,35 @@
|
|||
|
||||
# Configuration
|
||||
|
||||
ProzillaOS can be configured in numerous ways. The most important one being via the application itself, by going to the Settings app or directly changing the config files in the `~/.config` folder.
|
||||
ProzillaOS can be configured in numerous ways. The most important one being via the application itself, by going to the Settings app or directly changing the config files in the virtual `~/.config` folder.
|
||||
|
||||
As a developer, there are also the following ways to configure ProzillaOS:
|
||||
For developers, these are the methods of configuring ProzillaOS:
|
||||
|
||||
- `src/config` - The `src/config` directory holds all global variables used in the rest of the `src` directory, which are mostly string and number constants, but also includes some arrays and dictionaries that can be adjusted to configure ProzillaOS.
|
||||
- `styles` - Everything related to styles, can be configured in `styles` directory. Most configurations will happen inside `styles/global`, where you can define the fonts, css variables/properties and other details.
|
||||
- `public/config` - This directory has XML files that serve as the default data for config files used by the app in the virtual drive. These can be edited by the user once they're loaded during initialisation.
|
||||
|
||||
## Deployment
|
||||
|
||||
Before starting the deployment process, you will need to make sure these parts of your configuration are set up correctly.
|
||||
|
||||
### Domain
|
||||
|
||||
To change the domain that your website will be deployed to, go to [`branding.config.ts`](../../src/config/branding.config.ts) and set the `DOMAIN` variable to your own domain. You may also want to adjust the `BASE_URL` in case your domain does not have an SSL certificate. If you are using GitHub Pages, go to your Pages settings on GitHub and make sure the domain matches the one you just configured to deploy to.
|
||||
|
||||
> [!WARNING]
|
||||
> This configuration is also required before starting the staging process.
|
||||
|
||||
### Branch
|
||||
|
||||
If you are deploying to GitHub Pages, go to your Pages settings on GitHub, navigate to "Build and deployment" and set the source to "Deploy from a branch". Then select the `gh-pages` branch, select the `/ (root)` folder and click "Save". Make sure your domain matches the domain in your configuration, as described in the previous paragraph.
|
||||
|
||||
### Repository URL & commit message
|
||||
|
||||
If you are deploying to GitHub Pages, open [deploy.sh](../../deploy.sh) and set the `REPO_URL` variable to the URL of your GitHub repository. You may also want to customize the `COMMIT_MESSAGE` variable, which will be used to name commits made to the `gh-pages` branch.
|
||||
|
||||
## Branding
|
||||
|
||||
### Name
|
||||
|
||||
Change the variable called `NAME` in [`branding.config.ts`](../../src/config/branding.config.ts).
|
||||
|
|
@ -8,18 +8,22 @@ ProzillaOS is designed in Figma by Prozilla. You can view the design file [here]
|
|||
|
||||
<img src="../../public/assets/screenshots/screenshot-files-info-taskbar-desktop.png" alt="Screenshot of ProzillaOS"/>
|
||||
|
||||
### Font
|
||||
## Font
|
||||
|
||||
The font used by ProzillaOS is [Poppins](https://fonts.google.com/specimen/Poppins) from Google Fonts by Indian Type Foundry, Jonny Pinhorn.
|
||||
The font used by ProzillaOS is [Outfit](https://fonts.google.com/specimen/Outfit) from Google Fonts, designed by Smartsheet Inc, Rodrigo Fuenzalida.
|
||||
|
||||
### UI Icons
|
||||
## UI Icons
|
||||
|
||||
ProzillaOS uses [Font Awesome](https://fontawesome.com/) icons (some modified) in its UI.
|
||||
ProzillaOS uses original and modified [Font Awesome](https://fontawesome.com/) icons in its user interface.
|
||||
|
||||
### App Icons
|
||||
## App Icons
|
||||
|
||||
The apps use icons that are either modified versions of FontAwesome icons or custom icons, designed by Prozilla.
|
||||
The applications use icons that are either modified versions of FontAwesome icons or custom icons, designed by Prozilla.
|
||||
|
||||
### Color Palette
|
||||
## Color Palette
|
||||
|
||||
The color palette is the [Canadian Palette](https://flatuicolors.com/palette/ca) from Flat UI Colors 2 by Ahmet Sulek.
|
||||
The color palette is hand-made by Prozilla and is part of the design file.
|
||||
|
||||
## Wallpapers
|
||||
|
||||
The wallpapers are generated by Prozilla using a Figma extension called [Mesh Gradient](https://www.figma.com/community/plugin/958202093377483021/mesh-gradient).
|
||||
|
|
@ -2,10 +2,22 @@
|
|||
|
||||
# FAQ
|
||||
|
||||
### Q: What's the purpose of ProzillaOS?
|
||||
## Q: What's the purpose of ProzillaOS?
|
||||
|
||||
A: Obviously ProzillaOS doesn't solve any issues or anything like that. It's just a fun project I started because I wanted to refine my web development and design skills, as well as my React.js proficiency. At the same time, I also wanted to create an interesting and innovative web application and share it with the community via open source.
|
||||
A: Obviously ProzillaOS doesn't solve any issues or anything like that. It's just a fun project I started because I wanted to refine my web development and design skills, as well as my React.js proficiency. At the same time, I also wanted to create an interesting and innovative web application and share it with the community via open-source.
|
||||
|
||||
### Q: What tools did you use to make ProzillaOS?
|
||||
## Q: What tools did you use to make ProzillaOS?
|
||||
|
||||
A: I used Visual Studio Code for coding, Figma for designing, Notion for project management, GitHub for source control. I didn't use any libraries for the main parts of the OS. The libraries I used for specific purposes like certain applications or utilities, can be found in the `package.json` file. I got the icons from Font Awesome and the fonts from Google Fonts.
|
||||
A: I used Visual Studio Code for coding, Figma for designing, Notion for project management, GitHub for source control. I didn't use any libraries for the main parts of the OS. The libraries I used for specific purposes like certain applications or utilities, can be found in the `package.json` file. I got the icons from Font Awesome and the fonts from Google Fonts.
|
||||
|
||||
## Q: Is ProzillaOS free?
|
||||
|
||||
A: ProzillaOS is free and open-source. Check the [license](../../LICENSE.md) for more information about modifying and distributing ProzillaOS.
|
||||
|
||||
## Q: Why can't I install a certain program on ProzillaOS?
|
||||
|
||||
A: Because ProzillaOS is not a real operating system and does not use real applications. The available applications are custom React components, ProzillaOS can not interpret executable files or perform any task that it isn't programmed to do. However, there are plans for expanding ProzillaOS and enabling support for executable files and downloadable native extensions/applications.
|
||||
|
||||
## Q: Will you merge my pull request?
|
||||
|
||||
A: No, this is supposed to be a solo project. Despite the fact that I won't allow any contributions to this project, I encourage you to fork this project and create your own version. If you do so, don't hesitate to share it with me or with other people online!
|
||||
|
|
|
|||
|
|
@ -4,11 +4,17 @@
|
|||
|
||||
Most code for features can be found in the [features](../../src/features) directory. This directory is a library that is mostly used by files in the [components](../../src/components) and [hooks](../../src/hooks) directory.
|
||||
|
||||
> Note: Inside this part of the docs you will often see mentions of directories like `features` or `components`. These paths are relative to the `src` directory. The respective paths relative to the root of this project are `src/features` and `src/components`.
|
||||
> [!NOTE]
|
||||
> Mentions of directories inside this part of the documentation, are relative to the `src` folder.
|
||||
> ```
|
||||
> components -> src/components
|
||||
> hooks -> src/hooks
|
||||
> ```
|
||||
|
||||
To see the status and to-do's of each feature, check the [task board](https://prozilla.notion.site/8325fabca1fb4f9885b6d6dfd5aa64c8?v=1a59f7ce50914f5ea711fe6460e52868&pvs=4) on Notion.
|
||||
> [!TIP]
|
||||
> To see the status and to-do's of each feature, check the [task board](https://prozilla.notion.site/8325fabca1fb4f9885b6d6dfd5aa64c8?v=1a59f7ce50914f5ea711fe6460e52868&pvs=4) on Notion.
|
||||
|
||||
## Table of Contents
|
||||
## Pages
|
||||
|
||||
- [Actions](actions/README.md)
|
||||
- [Apps](apps/README.md)
|
||||
|
|
|
|||
|
|
@ -4,17 +4,33 @@
|
|||
|
||||
> Related document: [Windows](../windows/README.md)
|
||||
|
||||
Applications (often shortened to apps) are processes that open a window when ran. The window allows the user to view and interact with the app. Apps have a `title`, `id` and a `windowContent` property that refers to the React component of the application interface.
|
||||
Applications (often shortened to apps) are processes that open a window when ran. The window allows the user to view and interact with the app. Apps have a `name` and `id` property as well as a `windowContent` property that refers to the React component of the application interface.
|
||||
|
||||
> Some apps have a different name in the UI, these names are written between brackets and quotation marks. The other name is the one used in code and file/folder names.
|
||||
## Pages
|
||||
|
||||
## Table of Contents
|
||||
- [<img src="../../../public/assets/apps/icons/terminal.svg" width=20 height=20 style="vertical-align: text-bottom; background: none;"/> Commands (terminal)](terminal/README.md)
|
||||
- [<img src="../../../public/assets/apps/icons/file-explorer.svg" width=20 height=20 style="vertical-align: text-bottom; background: none;"/> Files (file-explorer)](file-explorer/README.md)
|
||||
- [<img src="../../../public/assets/apps/icons/media-viewer.svg" width=20 height=20 style="vertical-align: text-bottom; background: none;"/> Photos (media-viewer)](media-viewer/README.md)
|
||||
- [<img src="../../../public/assets/apps/icons/text-editor.svg" width=20 height=20 style="vertical-align: text-bottom; background: none;"/> Notes (text-editor)](text-editor/README.md)
|
||||
- [<img src="../../../public/assets/apps/icons/settings.svg" width=20 height=20 style="vertical-align: text-bottom; background: none;"/> Settings (settings)](settings/README.md)
|
||||
|
||||
- [<img src="../../../public/assets/apps/icons/terminal.svg" width=20 height=20 style="vertical-align: text-bottom; background: none;"/> Terminal ("Commands")](terminal/README.md)
|
||||
- [<img src="../../../public/assets/apps/icons/file-explorer.svg" width=20 height=20 style="vertical-align: text-bottom; background: none;"/> File Explorer ("Files")](file-explorer/README.md)
|
||||
- [<img src="../../../public/assets/apps/icons/media-viewer.svg" width=20 height=20 style="vertical-align: text-bottom; background: none;"/> Media Viewer ("Photos")](media-viewer/README.md)
|
||||
- [<img src="../../../public/assets/apps/icons/text-editor.svg" width=20 height=20 style="vertical-align: text-bottom; background: none;"/> Text Editor ("Notes")](text-editor/README.md)
|
||||
- [<img src="../../../public/assets/apps/icons/settings.svg" width=20 height=20 style="vertical-align: text-bottom; background: none;"/> Settings](settings/README.md)
|
||||
## Name VS ID
|
||||
|
||||
In the list above, you can see some app names, as well as the corresponding IDs, which are written between brackers and in kebab-case. App names are mainly used in user interfaces, may change at any point and can contain spaces. App IDs are mostly constrained within the development-side of ProzillaOS, generally will remain unchanged and can not contain spaces. See the table below for a list of use cases.
|
||||
|
||||
| Location | Uses ID | Uses name |
|
||||
| --- | --- | --- |
|
||||
| File & folder names | :heavy_check_mark: | :x: |
|
||||
| React components | :heavy_check_mark: | :x: |
|
||||
| Standalone URL | :heavy_check_mark: | :x: |
|
||||
| URL params | :heavy_check_mark: | :x: |
|
||||
| Static assets | :heavy_check_mark: | :x: |
|
||||
| Window title | :x: | :heavy_check_mark: |
|
||||
| Apps list | :x: | :heavy_check_mark: |
|
||||
| Standalone title | :x: | :heavy_check_mark: |
|
||||
|
||||
> [!CAUTION]
|
||||
> Changing the ID of an application that has already been deployed once may cause unexpected issues, like creating invalid links.
|
||||
|
||||
## Common components
|
||||
|
||||
|
|
@ -25,30 +41,24 @@ The header menu is a useful component that can be added to app windows for quick
|
|||
#### Example
|
||||
|
||||
```tsx
|
||||
// components/apps/_common/HeaderMenu.tsx
|
||||
|
||||
<HeaderMenu
|
||||
options={{
|
||||
"File": {
|
||||
"New": () => {
|
||||
// ...
|
||||
},
|
||||
"Save": () => {
|
||||
// ...
|
||||
},
|
||||
"Exit": () => {
|
||||
// ...
|
||||
},
|
||||
},
|
||||
}}
|
||||
shortcuts={{
|
||||
"File": {
|
||||
"New": ["Control", "e"],
|
||||
"Save": ["Control", "s"],
|
||||
"Exit": ["Control", "x"],
|
||||
},
|
||||
}}
|
||||
/>
|
||||
<HeaderMenu>
|
||||
<DropdownAction label="File" showOnHover={false}>
|
||||
<ClickAction label="New" onTrigger={/* ... */}/>
|
||||
<ClickAction label="Open" onTrigger={/* ... */} shortcut={["Control", "o"]}/>
|
||||
<ClickAction label="Save" onTrigger={/* ... */} shortcut={["Control", "s"]}/>
|
||||
<ClickAction label="Quit" onTrigger={/* ... */} shortcut={["Control", "q"]}/>
|
||||
</DropdownAction>
|
||||
<DropdownAction label="View" showOnHover={false}>
|
||||
<ClickAction
|
||||
label={currentMode === "view" ? "Edit mode" : "Preview mode"}
|
||||
onTrigger={/* ... */}
|
||||
shortcut={["Control", "v"]}
|
||||
/>
|
||||
<ClickAction label="Zoom in" onTrigger={/* ... */} shortcut={["Control", "+"]}/>
|
||||
<ClickAction label="Zoom out" onTrigger={/* ... */} shortcut={["Control", "-"]}/>
|
||||
<ClickAction label="Reset Zoom" onTrigger={/* ... */} shortcut={["Control", "0"]}/>
|
||||
</DropdownAction>
|
||||
</HeaderMenu>
|
||||
```
|
||||
|
||||
## App templates
|
||||
|
|
|
|||
|
|
@ -1,9 +0,0 @@
|
|||
[← Back](../README.md)
|
||||
|
||||
# SEO
|
||||
|
||||
## Tools
|
||||
|
||||
### [ICO converter](https://www.icoconverter.com/)
|
||||
|
||||
Convert an image into an ICO file with multiple resolutions.
|
||||
Loading…
Reference in a new issue