selfprivacy.org/README.md

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
```

You can view your site copy on any device connected to the same network. For example, if you're working on a laptop with address `192.168.1.99`, run:

```
hugo server --bind 192.168.1.99
```

The site will be available at `192.168.1.99:1313`, which you can also visit from another device, like your smartphone. If it doesn't work, check if your firewall blocks incoming connections over port `1313`. To use a different port, like `8080`, add `--port 8080`.

## 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