mirror of
https://git.selfprivacy.org/SelfPrivacy/selfprivacy.org.git
synced 2024-09-07 20:46:57 +00:00
166 lines
5.7 KiB
Markdown
166 lines
5.7 KiB
Markdown
This is a repository for the SelfPrivacy website, available at https://selfprivacy.org/
|
|
|
|
This website is statically generated using [Hugo][] and uses a customised version of the [Docsy][] theme. It is available in English and Russian.
|
|
|
|
## Getting started
|
|
1. Clone this repo with `git clone https://git.selfprivacy.org/SelfPrivacy/selfprivacy.org.git`
|
|
1. Run `hugo server`
|
|
1. Open `http://localhost:1313/` in your browser
|
|
|
|
If it doesn't work, check if you have [Hugo][] and dependencies installed.
|
|
|
|
If `1313` is already used for something else, Hugo will use a different port. Check your console to find out which one.
|
|
|
|
## Folder structure
|
|
|
|
```
|
|
content/ source files in .md and .html
|
|
assets/ assets that require preprocessing
|
|
Dockerfile
|
|
i18n/ UI translation strings
|
|
layouts/ copied customised theme files
|
|
LICENSE
|
|
node_modules/
|
|
public/ generated .html files
|
|
resources/ generated assets
|
|
static/ static assets
|
|
_vendor/ customisable theme files
|
|
package.json
|
|
package-lock.json
|
|
README.md <- you're here
|
|
go.mod
|
|
go.sum
|
|
config.toml website settings
|
|
netlify.toml
|
|
docker-compose.yaml
|
|
```
|
|
|
|
In the `content/` folder, there are two folders, one per each language. Language folders have similar contents:
|
|
|
|
```
|
|
blog/ blog and releases
|
|
docs/ documentation
|
|
download/ download page
|
|
privacy-policy/ privacy policy
|
|
_index.html the landing page
|
|
search.md
|
|
|
|
...other landing page files
|
|
```
|
|
|
|
### To add a new section or subsection
|
|
1. Create a new folder
|
|
1. Create a file called `_index.md` in that folder.
|
|
1. Add more files if needed; put images and videos in the same folder
|
|
|
|
### To add an image to the docs article
|
|
To add an image to an article, create a new folder and put the article and it's illustrations in that folder.
|
|
|
|
In the text use `imgproc` shortcode with explicit width and height:
|
|
```
|
|
{{< imgproc filename Fill "1001x808" />}}
|
|
```
|
|
|
|
### To change layout
|
|
Go to the `_vendor/github.com/google/docsy/layouts` and change files there. Do not copy files to the project's `layouts/` folder, it was used before the theme was vendored and will be removed later.
|
|
|
|
### To change styles
|
|
Change the `assets/scss/_styles_project.scss`. Use variables defined in the `_variables_project.scss`.
|
|
|
|
If you want to change the style of the Docsy theme components, navigate to `_vendor/github.com/google/docsy/assets/scss` and change files there instead.
|
|
|
|
### To reorder documentation pages
|
|
In all of markdown files, change the `weight` number in the metadata.
|
|
|
|
|
|
## Running the website locally
|
|
|
|
Building and running the site locally requires a recent `extended` version of [Hugo](https://gohugo.io).
|
|
You can find out more about how to install Hugo for your environment in the [Docsy Getting started guide](https://www.docsy.dev/docs/getting-started/#prerequisites-and-installation).
|
|
|
|
Once you've made your working copy of the site repo, from the repo root folder, run:
|
|
|
|
```
|
|
hugo server
|
|
```
|
|
|
|
## Running a container locally
|
|
|
|
You can run docsy-example inside a [Docker](https://docs.docker.com/)
|
|
container, the container runs with a volume bound to the `docsy-example`
|
|
folder. This approach doesn't require you to install any dependencies other
|
|
than [Docker Desktop](https://www.docker.com/products/docker-desktop) on
|
|
Windows and Mac, and [Docker Compose](https://docs.docker.com/compose/install/)
|
|
on Linux.
|
|
|
|
1. Build the docker image
|
|
|
|
```bash
|
|
docker-compose build
|
|
```
|
|
|
|
1. Run the built image
|
|
|
|
```bash
|
|
docker-compose up
|
|
```
|
|
|
|
> NOTE: You can run both commands at once with `docker-compose up --build`.
|
|
|
|
1. Verify that the service is working.
|
|
|
|
Open your web browser and type `http://localhost:1313` in your navigation bar,
|
|
This opens a local instance of the docsy-example homepage. You can now make
|
|
changes to the docsy example and those changes will immediately show up in your
|
|
browser after you save.
|
|
|
|
### Cleanup
|
|
|
|
To stop Docker Compose, on your terminal window, press **Ctrl + C**.
|
|
|
|
To remove the produced images run:
|
|
|
|
```console
|
|
docker-compose rm
|
|
```
|
|
For more information see the [Docker Compose
|
|
documentation](https://docs.docker.com/compose/gettingstarted/).
|
|
|
|
## Troubleshooting
|
|
|
|
As you run the website locally, you may run into the following error:
|
|
|
|
```
|
|
➜ hugo server
|
|
|
|
INFO 2021/01/21 21:07:55 Using config file:
|
|
Building sites … INFO 2021/01/21 21:07:55 syncing static files to /
|
|
Built in 288 ms
|
|
Error: Error building site: TOCSS: failed to transform "scss/main.scss" (text/x-scss): resource "scss/scss/main.scss_9fadf33d895a46083cdd64396b57ef68" not found in file cache
|
|
```
|
|
|
|
This error occurs if you have not [installed the extended version of Hugo](https://www.docsy.dev/docs/get-started/docsy-as-module/installation-prerequisites/#install-hugo).
|
|
|
|
Or you may encounter the following error:
|
|
|
|
```
|
|
➜ hugo server
|
|
|
|
Error: failed to download modules: binary with name "go" not found
|
|
```
|
|
|
|
This error occurs if you have not [installed the `go` programming language on your system](https://www.docsy.dev/docs/get-started/docsy-as-module/installation-prerequisites/#install-go-language).
|
|
|
|
## Useful links
|
|
|
|
- [Hugo](https://gohugo.io/documentation/)
|
|
- [Docsy](https://www.docsy.dev/docs/)
|
|
- [CommonMark](https://spec.commonmark.org/0.31.2/)
|
|
- [Sass](https://sass-lang.com/documentation/)
|
|
- [Bootstrap](https://getbootstrap.com/docs/5.3/getting-started/introduction/)
|
|
- [Spell Checker extension](https://open-vsx.org/extension/streetsidesoftware/code-spell-checker-russian)
|
|
|
|
[Hugo]: https://gohugo.io/documentation/
|
|
[Hugo theme module]: https://gohugo.io/hugo-modules/use-modules/#use-a-module-for-a-theme
|
|
[Docsy user guide]: https://docsy.dev/docs
|
|
[Docsy]: https://github.com/google/docsy |