You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Documentation for Polykey. This is mirrored to Gitlab at https://gitlab.com/MatrixAI/open-source/Polykey-Docs.
7
-
8
-
GitLab builds it via the CI/CD into static pages, rendering the markdown files and templates it within the branding of [polykey.com](https://polykey.com).
9
-
10
-
The CI/CD pushes it to [polykey.com/docs](https://polykey.com/docs) which is hosted by Cloudflare's pages and worker system.
3
+
Documentation for Polykey.
11
4
12
5
## Development
13
6
14
-
Run `nix-shell`, and once you're inside, you can use:
7
+
Run `nix develop`, and once you're inside, you can use:
15
8
16
9
```sh
17
10
# starts a local version
@@ -26,36 +19,33 @@ npm run lint
26
19
npm run lintfix
27
20
```
28
21
29
-
You need to do setup the `.env` from `.env.example` if you want to successfully deploy to Cloudflare.
30
-
31
-
We use Git LFS to store all media in `images/**`. It's important to ensure that `git-lfs` is installed on your system before you contribute anything (on NixOS, it is installed as a separate package to `git`). By default anything put under `images/**` when using `git add` (after LFS is setup) will be uploaded to LFS, and thus the repository will only have links. Because LFS is enabled, it is used on both GitHub and GitLab.
32
-
33
-
If this is the first time you cloned the repository, you must use `git lfs install` to ensure your local repository has LFS setup. It may be automatically setup if you already had it installed prior to cloning.
22
+
## Deployment
34
23
35
-
Pro-tip, if we need to make sure files that were accidentally not put into LFS must be put into LFS, the command to use is:
Sometimes when you change branches, certain LFS references may not yet be resolved, in those cases you should just use (such as doing a `git lfs migrate import`):
31
+
Production:
43
32
44
33
```sh
45
-
git lfs pull
34
+
npm run build
35
+
npm run deploy -- --env production
46
36
```
47
37
48
38
## Contributing
49
39
50
-
Because we use docusaurus, we can choose to write in markdown, TSX or MDX.
40
+
Because we use Docusaurus, we can choose to write in markdown, TSX or MDX.
51
41
52
42
### HTML Syntax
53
43
54
44
Sometimes markdown syntax just doesn't cut it, and HTML syntax needs to be used.
55
45
56
-
While `docusaurus` is flexible, GitHub/GitLab is not.
46
+
While Docusaurus is flexible, GitHub is not.
57
47
58
-
GitHub/GitLab will process the markdown and then sanitizes the HTML: https://github.com/github/markup#github-markup.
48
+
GitHub will process the markdown and then sanitizes the HTML: https://github.com/github/markup#github-markup.
59
49
60
50
There is a limited set of HTML tags are here: https://github.com/gjtorikian/html-pipeline/blob/03ae30d713199c2562951d627b98b75dc16939e4/lib/html/pipeline/sanitization_filter.rb#L40-L49
The former is markdown syntax, the latter is HTML tag.
76
66
77
-
In order to maintain portability, we always use absolute paths. This works on both GitHub/GitLab markdown rendering and also for `docusaurus`.
67
+
In order to maintain portability, we always use absolute paths. This works on both GitHub markdown rendering and also for Docusaurus.
78
68
79
-
On GitHub/GitLab, which renders the markdown directly, the relative paths are considered relative to the location of the markdown file referencing the path. The absolute paths are considered relative to the root of the project repository. Therefore because `images` directory is located at the project root, it ends up being routable.
69
+
On GitHub, which renders the markdown directly, the relative paths are considered relative to the location of the markdown file referencing the path. The absolute paths are considered relative to the root of the project repository. Therefore because the`images` directory is located at the project root, it ends up being routable.
80
70
81
-
With `docusaurus`, the absolute paths are looked up relative to `static` directory. Inside the `static` directory we have created symlinks pointing back to `../images`. This allows `docusaurus` to also resolve these paths which will be copied into the `/build/` directory.
71
+
With Docusaurus, the absolute paths are looked up relative to `static` directory. Inside the `static` directory we have created symlinks pointing back to `../images`. This allows Docusaurus to also resolve these paths which will be copied into the `/build/` directory.
82
72
83
-
Note that `docusaurus` doesn't do any special rendering for HTML tags, it uses the `src` as is. While markdown references will be further processed with webpack. It is therefore preferable to use markdown syntax instead. The `docusaurus` does support a variant of the HTML tag:
73
+
Note that Docusaurus doesn't do any special rendering for HTML tags, it uses the `src` as is. While markdown references will be further processed with webpack. It is therefore preferable to use markdown syntax instead. Docusaurus does support a variant of the HTML tag:
However this does not work in GitHub/GitLab. So this is not recommended to use.
79
+
However this does not work in GitHub. So this is not recommended to use.
90
80
91
-
Therefore if you want to add inline styles to an image and still use markdown syntax so you get the benefit of `docusaurus` asset processing, the styles must be applied outside the image reference in a surrounding tag:
81
+
Therefore if you want to add inline styles to an image and still use markdown syntax so you get the benefit of Docusaurus asset processing, the styles must be applied outside the image reference in a surrounding tag:
92
82
93
83
```md
94
84
<div align="center">
@@ -98,7 +88,7 @@ Therefore if you want to add inline styles to an image and still use markdown sy
98
88
</div>
99
89
```
100
90
101
-
Take note of the whitespace newlines between, if no newlines are used, GitHub/GitLab will interpret this as all HTML. Also note that `<p></p>` will not work.
91
+
Take note of the whitespace newlines between, if no newlines are used, GitHub will interpret this as all HTML. Also note that `<p></p>` will not work.
102
92
103
93
Note that this won't work for resizing the images unfortunately. You have to apply the `width` attribute directly to the `<img />` tag. See: https://github.com/facebook/docusaurus/discussions/6465 for more information.
104
94
@@ -119,14 +109,6 @@ The `pathname://` bypasses the client side routing forcing server side routing.
119
109
120
110
The `target: '_self'` ensures that the same frame is used instead of creating a new frame.
121
111
122
-
## Deployment
123
-
124
-
You need to setup `.env` from `.env.example`.
125
-
126
-
Then you can build `npm run build`.
127
-
128
-
Finally run `npm run deploy`.
129
-
130
-
This will deploy the development workers first.
112
+
## License
131
113
132
-
If you want to deploy production workers, you have to `npm run deploy -- --env production`.
114
+
Polykey-Docs is licensed under GPL-3.0, you may read the terms of the license [here](LICENSE).
0 commit comments