torproject/lego
1
0
Fork 0
mirror of https://github.com/torproject/lego.git synced 2024-11-22 17:19:46 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity
building blocks for tor project websites
565 Commits 40 Branches 0 Tags 42 MiB
JavaScript 43.6%
SCSS 31.5%
HTML 15.8%
Python 8%
CSS 0.9%
Other 0.2%
main
Go to file
Jérôme Charaoui a27d8b77d3
translate content files earlier in build 
this moves the translation of contents.lr files earlier in the build
process, in `on_before_build_all` instead of `on_before_build`, to
ensure that the build queue accounts for the alternative content files
(`contents+*.lr`) during the build process, instead of requiring
multiple (expensive) build runs

the caveat is that translated alternative contents files are now only
produced during a full build, which likely breaks "on-the-fly" creation
of those files when authoring using the Lektor web admin interface
2024-10-28 09:18:22 -04:00
.github Add .github/FUNDING.yml 2019-09-12 15:45:52 +02:00
assets allow language menu to overlap yec banner 2024-10-23 14:05:55 -04:00
content/robots.txt Add an extensible template for robots.txt 2022-06-29 18:04:42 -07:00
databags add new tpo translations be, el, tk. ref: tpo/web/tpo#419 2024-02-21 13:49:14 +00:00
models support external URLs in redirect template 2024-07-30 12:24:13 -04:00
packages translate content files earlier in build 2024-10-28 09:18:22 -04:00
scripts Update sass version 2022-12-22 09:34:51 -08:00
templates cleanup obsolete macro 2024-10-23 13:11:08 -04:00
.gitignore Add translated content files to gitignore 2023-09-25 18:00:47 +02:00
help Update css 2019-11-05 14:54:52 +01:00
lektor-requirements.txt Add lektor-markdown-image-attrs to lektor requirements 2022-12-20 11:05:58 -08:00
README.md Add documentation about lektor-scss to README 2023-01-30 14:32:29 -08:00

README.md

Lego

This repository contains templates, models, assets, databags, and lektor plugins used by many of the lektor sites. It's intended to be added as a submodule, to keep the style and assets up-to-date between sites.

You won't use this repo directly. You'll usually clone it as a submodule:

git clone https://gitlab.torproject.org/tpo/web/tpo
cd tpo
git submodule update --init

# or
git clone --recurse-submodules https://gitlab.torproject.org/tpo/web/tpo

You might also want to add it to a new lektor project. This is a three-step process:

  1. Clone the submodule from the project root: git submodule add https://gitlab.torproject.org/tpo/web/lego.git
  2. Edit the submodule URL. See <#relative-submodule-urls>.
  3. Symlink everything you need. See <#symlinking-lego>.

Relative submodule URLs

Gitlab CI requires that submodules hosted on the same server as the main repo use relative URLs. If your project isn't hosted on https://gitlab.torproject.org or isn't using Gitlab CI, you can skip this!

Relative submodule URLs means that if lego is located at https://gitlab.torproject.org/tpo/web/lego and your project is https://gitlab.torproject.org/tpo/web/some_website, then your submodule URL should be ../lego.git The .git suffix is required. If your project is hosted in your own namespace (like a fork), your repo URL should look like https://gitlab.torproject.org/user/repo your submodule URL should be ../../tpo/web/lego.git. This means that forking requires you to change your submodule URL to use CI. This is a known bug with upstream gitlab https://gitlab.com/gitlab-org/gitlab-runner/-/issues/3374 and TPA is looking into solutions in the meantime.

Symlinking lego

Adding lego as a submodule doesn't actually do anything on its own. You'll need to symlink the parts of lego that you want. For instance, lektor installs all the python packages in /packages. Symlinking /lego/packages to /packages means lektor will install all the packages lego comes with. You can even pick and choose what packages get symlinked: mkdir -p packages && ln -s ../lego/lektor-md-tag ../lego/npm-support packages

A list of things contained in lego and descriptions of them is <#package-may-contain>. Usually, you'll want to symlink /lego/assets/* to /assets, /lego/templates/* to /templates, /lego/databags/* to /databags*, and the entire /lego/packages directory to /packages

Package may contain

Here's what's inside lego:

  • assets/
    • assets/javascript/: Contains the javascript used by bootstrap
    • assets/scss/: Contains the SCSS for lego. This is Bootstrap v4, with our own styles layered on top
    • assets/static/: Contains fonts, images, and minified bootstrap js, as well as the compiled SCSS output
  • databags/: All the databags used by the lego templates
  • models/: Contains a model for redirect pages
  • packages/: A number of mirrored and patched python packages. See each package's README for details
  • templates/: Useful templates used by several of the sites

SCSS

The previous SCSS workflow for lego was to store all the scss in the lego repo, alongside the resulting compiled CSS files. This meant that any change to the SCSS also had to include the compiled CSS, leading to MRs and diffs with tens of thousands of changed lines, which were usually just whitespace and formatting changes to the CSS.

In lego issue #55, the prebuilt bootstrap CSS was removed from lego, and all sites now include the web team's fork of the lektor-scss plugin so that the SCSS is built as part of the lektor build process. Our lektor CI build process uses this plugin as well.

The lektor-scss plugin requires the dart sass compiler to be in your PATH. The sass binary installed by npm will not be able to build our SCSS, since we use the math.div function which is only available in the dart sass compiler.

If you need to install the dart sass compiler, the lego wiki has a helper script to install it for you. Just be sure to add $HOME/bin to your PATH variable!

NOTE: like lektor-i18n, the lektor-scss plugin requires you to build a lektor site at least twice, or lektor won't be able to resolve the bootstrap-*.css asseturl.

License

TBD

Lego (and all of TPO's web projects unless otherwise specified) do not yet have a license.