... | @@ -70,27 +70,57 @@ git submodule update --init --recursive --remote |
... | @@ -70,27 +70,57 @@ git submodule update --init --recursive --remote |
|
|
|
|
|
This will clone lego into the `./lego/` directory. Your local copy of the site will already have symlinks set up to point to lego files where needed.
|
|
This will clone lego into the `./lego/` directory. Your local copy of the site will already have symlinks set up to point to lego files where needed.
|
|
|
|
|
|
### 7. Install and use Lektor i18n plugin
|
|
### 7. Install the website's python dependencies
|
|
|
|
|
|
The plugins are installed when you start the lektor server locally or you build the website.
|
|
Our websites use a number of lektor plugins to work. To be consistent in what python packages are used for the plugins and their dependencies, we use a few different `requirements.txt` files to install python packages.
|
|
|
|
|
|
|
|
Activate your virtual environment, and then install the requirements:
|
|
|
|
|
|
|
|
```
|
|
|
|
source venv/bin/activate
|
|
|
|
pip install -r lego/requirements.txt
|
|
|
|
pip install -r requirements.txt
|
|
|
|
```
|
|
|
|
|
|
|
|
### 8. Build the website for the first time
|
|
|
|
|
|
|
|
Several of our plugins (lektor-i18n and lektor-scss) require that the lektor site be built twice. If you only build once, you'll be missing things like CSS or translations. Run `lektor build -f scss` and wait for the build to finish before developing on the website. Once you've waited for this initial build, you should be able to develop on the site normally.
|
|
|
|
|
|
|
|
You've finished setting up your development environment, congratulations!
|
|
|
|
|
|
|
|
### 9. Making changes to the website
|
|
|
|
|
|
|
|
Now that you've got your dev environment, it's time to start actually making changes to the site.
|
|
|
|
|
|
|
|
#### Building the website
|
|
|
|
|
|
|
|
Run `lektor build -f scss` to build the website. The `-f scss` part of the command enables the [lektor-scss](https://gitlab.torproject.org/tpo/web/lektor-scss/) plugin. Most of our sites use the scss plugin, but not all of them. As of right now the easiest way to find out if a site uses the scss plugin is to run this command:
|
|
|
|
|
|
|
|
```
|
|
|
|
grep -q 'LEKTOR_BUILD_FLAGS: *scss' .gitlab-ci.yml && echo 'this site uses the lektor-scss plugin' || echo "this site doesn't use the scss plugin"
|
|
|
|
```
|
|
|
|
|
|
|
|
Some websites need additional `-f` flags. You should check the README file of the site to find out what plugins it needs. If the site doesn't have a README file, you can also check the `.gitlab-ci.yml` file, and look for the line starting with `LEKTOR_BUILD_FLAGS:`
|
|
|
|
|
|
|
|
> **Tip**: When you build a site that uses more than one flag, remember to include `-f` before each one, like this: `lektor build -f flag1 -f flag2`
|
|
|
|
|
|
|
|
#### Changing the content
|
|
|
|
|
|
|
|
Lektor content uses a set of directories and `contents.lr` files to define the structure of the site. You can find these `contents.lr` files in the `content/` directory. See the [Writing Content](https://gitlab.torproject.org/torproject/web/team/wikis/Writing-the-content) wiki page for more information.
|
|
|
|
|
|
|
|
#### Translations
|
|
|
|
|
|
The translation mechanism is hooked into the build system, so translating a website just means building the website. You can learn more about the translation process [here](https://gitlab.torproject.org/tpo/community/l10n/-/wikis/Home).
|
|
The translation mechanism is hooked into the build system, so translating a website just means building the website. You can learn more about the translation process [here](https://gitlab.torproject.org/tpo/community/l10n/-/wikis/Home).
|
|
|
|
|
|
`lektor build -O <folder>` builds the website in a folder of your choice
|
|
#### Running a local dev server
|
|
|
|
|
|
|
|
`lektor s` runs a lektor server and allows you to have the website updating on <http://localhost:5000>. You can try this out by running the server and accessing it on your browser. Remember to include any `-f` build flags in the lektor command!
|
|
|
|
|
|
`lektor s` runs a lektor server and allows you to have the website updating on `http://localhost:5000`. You can try this out by running the server and accessing it on your browser.
|
|
|
|
Note: It will not work on Tor Browser. :)
|
|
Note: It will not work on Tor Browser. :)
|
|
|
|
|
|
**NOTE:** Due to how the lektor-i18n-plugin works, you'll need to build the lektor site twice after cloning it to get the translation files in place. Once you've done that, You can just build a single time like normal to see your changes.
|
|
|
|
|
|
|
|
> **Tip**: To save some time while you build in local, you can edit the [configs/i18n.ini](https://gitweb.torproject.org/project/web/tpo.git/tree/configs/i18n.ini) file and take some languages out of the 'translations' option.
|
|
> **Tip**: To save some time while you build in local, you can edit the [configs/i18n.ini](https://gitweb.torproject.org/project/web/tpo.git/tree/configs/i18n.ini) file and take some languages out of the 'translations' option.
|
|
|
|
|
|
You can make changes to the pages. Most of [the content is on the `content/` folder](https://gitlab.torproject.org/torproject/web/tpo/wikis/Writing-the-content).
|
|
|
|
|
|
|
|
### 8. Finally, local server
|
|
|
|
enter `$ lektor server` to run a local continuous builder.
|
|
|
|
You should be able to access your local lektor instance at [http://127.0.0.1:5000/](http://127.0.0.1:5000/) from your computer.
|
|
|
|
|
|
|
|
# Most common lektor errors
|
|
# Most common lektor errors
|
|
|
|
|
|
##### FileNotFoundError:
|
|
##### FileNotFoundError:
|
... | | ... | |