Browse Source

Improve documentation (#1335)

* Fix "overriden" to "overridden" typo

* Add my website to the EXAMPLES

* HTTPS migration for some links

* Fix #1295 - Document alpine linux version

Fixes: #1295

* Update Zola version on Travis CI example

* Documentation improvements and typo fixes

* Update more example versions and remove the useless variable on the GitLab CI example

* Fix all broken links and theme links
master
William Desportes 5 months ago
committed by GitHub
parent
commit
afd5da4f64
No known key found for this signature in database GPG Key ID: 4AEE18F83AFDEB23
  1. 1
      EXAMPLES.md
  2. 4
      components/config/src/config/mod.rs
  3. 2
      docs/content/documentation/content/sass.md
  4. 2
      docs/content/documentation/content/search.md
  5. 24
      docs/content/documentation/deployment/github-pages.md
  6. 12
      docs/content/documentation/deployment/gitlab-pages.md
  7. 4
      docs/content/documentation/deployment/netlify.md
  8. 4
      docs/content/documentation/deployment/vercel.md
  9. 2
      docs/content/documentation/getting-started/directory-structure.md
  10. 25
      docs/content/documentation/getting-started/installation.md
  11. 4
      docs/content/documentation/themes/creating-a-theme.md
  12. 4
      docs/content/themes/DeepThought/index.md
  13. 2
      docs/content/themes/Zulma/index.md
  14. 2
      docs/content/themes/anpu/index.md
  15. 6
      docs/content/themes/codinfox-zola/index.md
  16. 2
      docs/content/themes/docsascode-theme/index.md
  17. 2
      docs/content/themes/lightspeed/index.md
  18. BIN
      docs/content/themes/oceanic-zen/screenshot-index.png
  19. 2
      docs/content/themes/toucan/index.md
  20. 2
      docs/content/themes/zerm/index.md
  21. 2
      docs/content/themes/zola-theme-hikari/index.md
  22. 2
      docs/content/themes/zola.386/index.md
  23. 2
      test_site/themes/sample/templates/section.html
  24. 2
      test_site/themes/sample/templates/shortcodes/pirate_included.html

1
EXAMPLES.md

@ -3,6 +3,7 @@
| Site | Source Code |
|:-------------------------------------------------------------------|:--------------------------------------------------------:|
| [vincentprouillet.com](https://www.vincentprouillet.com/) | https://github.com/Keats/vincentprouillet/ |
| [blog.williamdes.eu](http://blog.williamdes.eu/) | https://github.com/wdesportes/blog.williamdes.eu |
| [t-rex.tileserver.ch](https://t-rex.tileserver.ch) | https://github.com/t-rex-tileserver/t-rex-website/ |
| [Philipp Oppermann's blog](https://os.phil-opp.com/) | https://github.com/phil-opp/blog_os/tree/master/blog |
| [seventeencups](https://www.seventeencups.net) | https://github.com/17cupsofcoffee/seventeencups.net |

4
components/config/src/config/mod.rs

@ -259,7 +259,7 @@ impl Config {
fn add_theme_extra(&mut self, theme: &Theme) -> Result<()> {
for (key, val) in &theme.extra {
if !self.extra.contains_key(key) {
// The key is not overriden in site config, insert it
// The key is not overridden in site config, insert it
self.extra.insert(key.to_string(), val.clone());
continue;
}
@ -515,7 +515,7 @@ truc = "default"
assert_eq!(extra["hello"].as_str().unwrap(), "world".to_string());
assert_eq!(extra["a_value"].as_integer().unwrap(), 10);
assert_eq!(extra["sub"]["foo"].as_str().unwrap(), "bar".to_string());
assert_eq!(extra["sub"].get("truc").expect("The whole extra.sub table was overriden by theme data, discarding extra.sub.truc").as_str().unwrap(), "default".to_string());
assert_eq!(extra["sub"].get("truc").expect("The whole extra.sub table was overridden by theme data, discarding extra.sub.truc").as_str().unwrap(), "default".to_string());
assert_eq!(extra["sub"]["sub"]["foo"].as_str().unwrap(), "bar".to_string());
assert_eq!(
extra["sub"]["sub"]

2
docs/content/documentation/content/sass.md

@ -8,7 +8,7 @@ maintenance of large sets of CSS rules. If you're curious about what Sass
is and why it might be useful for styling your static site, the following links
may be of interest:
* The [official Sass website](http://sass-lang.com/)
* The [official Sass website](https://sass-lang.com/)
* [Why Sass?](https://alistapart.com/article/why-sass), by Dan Cederholm
## Using Sass in Zola

2
docs/content/documentation/content/search.md

@ -22,5 +22,5 @@ the JavaScript/CSS code to do an actual search and display results. You can look
implements it to get an idea: [search.js](https://github.com/getzola/zola/tree/master/docs/static/search.js).
## Configuring the search index
In some cases, the default indexing strategy is not suitable. You can customise which fields to include and whether
In some cases, the default indexing strategy is not suitable. You can customize which fields to include and whether
to truncate the content in the [search configuration](@/documentation/getting-started/configuration.md).

24
docs/content/documentation/deployment/github-pages.md

@ -33,19 +33,19 @@ on: push
name: Build and deploy GH Pages
jobs:
build:
name: shalzz/zola-deploy-action
name: Deploy
runs-on: ubuntu-latest
steps:
# Checkout
- uses: actions/checkout@master
# Build & deploy
- name: shalzz/zola-deploy-action
uses: shalzz/zola-deploy-action@v0.12.0
env:
# Target branch
PAGES_BRANCH: gh-pages
# Provide personal access token
TOKEN: ${{ secrets.TOKEN }}
# Checkout
- uses: actions/checkout@v2
# Build & deploy
- name: Deploy to gh-pages branch
uses: shalzz/zola-deploy-action@v0.13.0
env:
# Target branch
PAGES_BRANCH: gh-pages
# Provide personal access token
TOKEN: ${{ secrets.TOKEN }}
```
This script is pretty simple, because the [zola-deploy-action](https://github.com/shalzz/zola-deploy-action) is doing everything for you. You just need to provide some details. For more configuration options check out the [README](https://github.com/shalzz/zola-deploy-action/blob/master/README.md).
@ -98,7 +98,7 @@ language: minimal
before_script:
# Download and unzip the zola executable
# Replace the version numbers in the URL by the version you want to use
- curl -s -L https://github.com/getzola/zola/releases/download/v0.9.0/zola-v0.9.0-x86_64-unknown-linux-gnu.tar.gz | sudo tar xvzf - -C /usr/local/bin
- curl -s -L https://github.com/getzola/zola/releases/download/v0.13.0/zola-v0.13.0-x86_64-unknown-linux-gnu.tar.gz | sudo tar xvzf - -C /usr/local/bin
script:
- zola build

12
docs/content/documentation/deployment/gitlab-pages.md

@ -40,24 +40,22 @@ To do this, create a file called `.gitlab-ci.yml` in the root directory of your
image: alpine:latest
variables:
# This variable will ensure that the CI runner pulls in your theme from the submodule
GIT_SUBMODULE_STRATEGY: recursive
# Specify the zola version you want to use here
ZOLA_VERSION: "v0.12.0"
GIT_SUBMODULE_STRATEGY: recursive
pages:
script:
# Install the zola package from the alpine community repositories
- apk add --update-cache --repository http://dl-3.alpinelinux.org/alpine/edge/community/ zola
- apk add --update-cache --repository http://dl-cdn.alpinelinux.org/alpine/edge/community/ zola
# Execute zola build
- zola build
artifacts:
paths:
# Path of our artifacts
- public
# This config will only publish changes that are pushed on the master branch
only:
only:
- master
```

4
docs/content/documentation/deployment/netlify.md

@ -17,7 +17,7 @@ Once you are in the admin interface, you can add a site from a Git provider (Git
- build command: `zola build` (replace the version number in the variable by the version you want to use)
- publish directory: the path to where the `public` directory is
- image selection: `Ubuntu Xenial 16.04 (default)`
- Environment variables: `ZOLA_VERSION` with for example `0.8.0` as value
- Environment variables: `ZOLA_VERSION` with for example `0.13.0` as value
With this setup, your site should be automatically deployed on every commit on master. For `ZOLA_VERSION`, you may
use any of the tagged `release` versions in the GitHub repository. Netlify will automatically fetch the tagged version
@ -38,7 +38,7 @@ command = "zola build"
[build.environment]
# Set the version name that you want to use and Netlify will automatically use it.
ZOLA_VERSION = "0.9.0"
ZOLA_VERSION = "0.13.0"
# The magic for deploying previews of branches.
# We need to override the base url with whatever url Netlify assigns to our

4
docs/content/documentation/deployment/vercel.md

@ -23,11 +23,11 @@ After the import, you can set the settings for your project.
All we have to is include a `vercel.json` in our project's root directory by
specifying the `ZOLA_VERSION` we want to use to deploy the site.
```
```json
{
"build": {
"env": {
"ZOLA_VERSION": "0.12.0"
"ZOLA_VERSION": "0.13.0"
}
}
}

2
docs/content/documentation/getting-started/directory-structure.md

@ -32,7 +32,7 @@ that contains [pages](@/documentation/content/page.md) (your `.md` files).
To learn more, read the [content overview page](@/documentation/content/overview.md).
## `sass`
Contains the [Sass](http://sass-lang.com) files to be compiled. Non-Sass files will be ignored.
Contains the [Sass](https://sass-lang.com) files to be compiled. Non-Sass files will be ignored.
The directory structure of the `sass` folder will be preserved when copying over the compiled files; for example, a file at
`sass/something/site.scss` will be compiled to `public/something/site.css`.

25
docs/content/documentation/getting-started/installation.md

@ -10,7 +10,7 @@ Zola provides pre-built binaries for MacOS, Linux and Windows on the
Zola is available on [Brew](https://brew.sh):
```bash
```sh
$ brew install zola
```
@ -18,10 +18,18 @@ $ brew install zola
Zola is available in the official Arch Linux repositories.
```bash
```sh
$ pacman -S zola
```
### Alpine Linux
Zola is available in the official Alpine Linux repository, only on the `edge` version for now.
```sh
$ apk add zola --repository http://dl-cdn.alpinelinux.org/alpine/edge/community/
```
### Fedora
Zola has been available in the official repositories since Fedora 29.
@ -31,6 +39,7 @@ $ sudo dnf install zola
```
### Void Linux
Zola is available in the official Void Linux repositories.
```sh
@ -46,6 +55,7 @@ $ pkg install zola
```
### OpenBSD
Zola is available in the official package repository.
```sh
@ -56,27 +66,28 @@ $ doas pkg_add zola
Zola is available on snapcraft:
```bash
```sh
$ snap install --edge zola
```
## Windows
Zola is available on [Scoop](http://scoop.sh):
Zola is available on [Scoop](https://scoop.sh):
```bash
```sh
$ scoop install zola
```
and [Chocolatey](https://chocolatey.org/):
```bash
```sh
$ choco install zola
```
Zola does not work in PowerShell ISE.
## From source
To build Zola from source, you will need to have Git, [Rust (at least 1.45) and Cargo](https://www.rust-lang.org/)
installed. You will also need to meet additional dependencies to compile [libsass](https://github.com/sass/libsass):
@ -98,7 +109,7 @@ installed. You will also need to meet additional dependencies to compile [libsas
From a terminal, you can now run the following command:
```bash
```sh
$ cargo build --release
```

4
docs/content/documentation/themes/creating-a-theme.md

@ -23,7 +23,7 @@ min_version = "0.4.0"
# An optional live demo URL
demo = ""
# Any variable there can be overriden in the end user `config.toml`
# Any variable there can be overridden in the end user `config.toml`
# You don't need to prefix variables by the theme name but as this will
# be merged with user data, some kind of prefix or nesting is preferable
# Use snake_casing to be consistent with the rest of Zola
@ -38,7 +38,7 @@ homepage = "https://vincent.is"
# the info of the original author here
[original]
author = "mdo"
homepage = "http://markdotto.com/"
homepage = "https://markdotto.com/"
repo = "https://www.github.com/mdo/hyde"
```

4
docs/content/themes/DeepThought/index.md

@ -12,7 +12,7 @@ repository = "https://github.com/RatanShreshtha/DeepThought.git"
homepage = "https://github.com/RatanShreshtha/DeepThought"
minimum_version = "0.9.0"
license = "MIT"
demo = "https://zen-austin-0c80be.netlify.app/"
demo = "https://deepthought-theme.netlify.app/"
[extra.author]
name = "Ratan Kulshreshtha"
@ -24,7 +24,7 @@ homepage = "https://ratanshreshtha.dev"
![DeepThought](./screenshot.png)
# [Live Demo](https://zen-austin-0c80be.netlify.app/)
# [Live Demo](https://deepthought-theme.netlify.app/)
## Installation
Get [Zola](https://www.getzola.org/) and/or follow their guide on [installing a theme](https://www.getzola.org/documentation/themes/installing-and-using-themes/).

2
docs/content/themes/Zulma/index.md

@ -23,7 +23,7 @@ homepage = ""
A Bulma theme for Zola. See a live preview [here](https://festive-morse-47d46c.netlify.com/)
![Zulma Screenshot](/screenshot.png)
![Zulma Screenshot](./screenshot.png)
## Contents

2
docs/content/themes/anpu/index.md

@ -21,7 +21,7 @@ homepage = "https://zbrox.com"
# Anpu theme for Zola
This is a port of the Hugo theme [Anubis](https://github.com/Mitrichius/hugo-theme-anubis/tree/master/layouts) for [Zola](https://getzola.com).
This is a port of the Hugo theme [Anubis](https://github.com/Mitrichius/hugo-theme-anubis/tree/master/layouts) for [Zola](https://getzola.org).
![screenshot](screenshot.png)

6
docs/content/themes/codinfox-zola/index.md

@ -21,11 +21,11 @@ homepage = "https://svavs.github.io/"
# Codinfox-Zola
This is a [Zola](https://www.getzola.com) theme inspired to [Codinfox-Lanyon](https://codinfox.github.com/), a Lanyon based theme for [Jekyll](http://jekyllrb.com). See a live demo [here](https://codinfox-zola.vercel.app/).
This is a [Zola](https://www.getzola.org) theme inspired to [Codinfox-Lanyon](https://codinfox.github.com/), a Lanyon based theme for [Jekyll](http://jekyllrb.com). See a live demo [here](https://codinfox-zola.vercel.app/).
This theme places content first by tucking away navigation in a hidden drawer.
* Built for [Zola](https://www.getzola.com)
* Built for [Zola](https://www.getzola.org)
* Developed on GitHub and hosted for free on [GitHub Pages](https://pages.github.com)
* Coded with [Spacemacs](https://www.spacemacs.org)
@ -66,7 +66,7 @@ If you want to have a Blog with this theme, then create a folder inside the `con
## License
Open sourced under the [MIT license](LICENSE.md).
Open sourced under the [MIT license](https://github.com/svavs/codinfox-zola/blob/master/LICENSE.md).
## TODO

2
docs/content/themes/docsascode-theme/index.md

@ -21,7 +21,7 @@ homepage = "https://codeandmedia.com"
**Demo: [docsascode.codeandmedia.com](http://docsascode.codeandmedia.com)**
I was inspired by [Linode's approach](https://www.linode.com/2020/01/17/docs-as-code-at-linode/) to creating and managing docs. They call it _docs as code methodology._ Thereby my aim was making simple and productive way to work with any sort of documents and articles through Markdown, Git and Docker/k8s optionally.
I was inspired by [Linode's approach](https://www.linode.com/blog/linode/docs-as-code-at-linode/) to creating and managing docs. They call it _docs as code methodology._ Thereby my aim was making simple and productive way to work with any sort of documents and articles through Markdown, Git and Docker/k8s optionally.
The repo contains a theme for [Zola](https://www.getzola.org/) (the best static site generator I've ever seen) and dockerfile for building Docker images with Nginx-alpine. You can pull to your Docker an [image with demo-content](https://hub.docker.com/r/codeandmedia/docsascode-theme)

2
docs/content/themes/lightspeed/index.md

@ -142,7 +142,7 @@ This template is based on the Jekyll template [Light Speed Jekyll](https://githu
## License
Open sourced under the [MIT license](LICENSE.md).
Open sourced under the [MIT license](https://github.com/bradleytaunt/lightspeed/blob/master/LICENSE.md).
This project is open source except for example articles found in `content`.

BIN
docs/content/themes/oceanic-zen/screenshot-index.png

After

Width: 1943  |  Height: 1000  |  Size: 48 KiB

2
docs/content/themes/toucan/index.md

@ -12,7 +12,7 @@ repository = "https://git.42l.fr/HugoTrentesaux/toucan.git"
homepage = "https://git.42l.fr/HugoTrentesaux/toucan"
minimum_version = "0.8.0"
license = "AGPL"
demo = "http://blog.coinduf.eu/"
demo = "https://coinduf.eu/"
[extra.author]
name = "Hugo Trentesaux"

2
docs/content/themes/zerm/index.md

@ -23,7 +23,7 @@ homepage = "https://github.com/ejmg"
a minimalist and dark theme for [Zola](https://getzola.org).
![Screenshot](../master/zerm-preview.png?raw=true)
![screenshot](./screenshot.png)
[**Live Preview!**](https://zerm.ejmg.now.sh/)

2
docs/content/themes/zola-theme-hikari/index.md

@ -57,7 +57,7 @@ enable_mathjax = false
## License
[MIT](LICENSE)
[MIT](https://github.com/waynee95/zola-theme-hikari/blob/master/LICENSE)
Thanks to [Mathieu Mayer-Mazzoli](https://github.com/mx3m) for creating this awesome theme!

2
docs/content/themes/zola.386/index.md

@ -21,7 +21,7 @@ homepage = "https://github.com/lopes"
# ZOLA.386
![ZOLA.386 screenshot](https://github.com/lopes/zola.386/blob/master/screenshot.png?raw=true)
![ZOLA.386 screenshot](./screenshot.png)
## [Live demo](https://zola386.netlify.app/)

2
test_site/themes/sample/templates/section.html

@ -1,4 +1,4 @@
{% extends 'index.html' %}
{% block content %}
I'm overriden in all cases so seeing me is a bug
I'm overridden in all cases so seeing me is a bug
{% endblock %}

2
test_site/themes/sample/templates/shortcodes/pirate_included.html

@ -1 +1 @@
SHOULDNOTAPPEAR: overriden by site shortcode
SHOULDNOTAPPEAR: overridden by site shortcode
Loading…
Cancel
Save