neilotoole / sq-web

sq-web

sq.io website

This is the repo for the sq.io website, which hosts documentations for sq.

This site is built using:

• Hugo site generator
• Doks theme
• Node.js tooling
• Netlify hosting

Changes to the master branch kick off a redeploy on Netlify.

Contributing

You could open an issue, but ideally you'd submit a pull request.

1. Clone this repo

git clone https://github.com/neilotoole/sq-web.git && cd sq-web

2. Install dependencies

npm install

3. Make changes and test locally

# Start a local webserver on http://localhost:1313 to test you changes.
# Note that it may take a minute or longer for the site to be served (and
# you may not receive any indication of this). Be patient.
npm start

# Run linters, link checks, etc.
npm test

4. Submit a Pull Request

Create a Pull Request, providing context for your changes.

Redirects

• You can use the Hugo alias mechanism to maintain an old path that will redirect to the new path.
• If you need a redirect that's not associated with Hugo content, add an entry to the static/_redirects file. This is what the site uses to serve the sq.io/install.sh script.

Misc

• Doks comes with commands for common tasks.
• Use npm run gen:syntax-css to regenerate the syntax highlight theme. The themes (light and dark) are specified in generate-syntax-css.sh.

Asciinema

The site makes use of asciinema via the gohugo-asciinema Hugo module.

Typically, casts are stored in ./static/casts. To include a cast, use this shortcode:

{{< asciicast src="/casts/home-quick.cast" theme="monokai" poster="npt:0:20" rows="10" speed="1.5" idleTimeLimit="3" >}}

• poster="npt:0:20" specifies that the "poster" or cover image should be taken from 0m20s into the cast.
• Add autoPlay="true" if the cast should start immediately. This is usually not the case.

If you see this problem:

Error: Error building site: "content/en/_index.md:9:1": failed to extract shortcode: template for shortcode "asciicast" not found

It probably means that the hugo module cache is out of whack. Run npm install and try again.

Documentation

• Netlify
• Hugo
• Doks

Communities

• sq discussions
• Netlify Community
• Hugo Forums
• Doks Discussions

Acknowledgements

• Special thanks to Netlify, who provide free hosting for sq.io via their open source program.
• A bunch of stuff has been lifted from the Docsy theme.