Skip to content

Website Contribution

Please and Thank You🔗

The YS website needs your help! Especially with the documentation.

Everyone is welcome to contribute to the website, and your contributions are greatly appreciated.

About this Website🔗

Read This Page to learn how this website combined Material for MkDocs with YS to make a site that is super easy to contribute to.

How to Contribute🔗

The yamlscript.org website is designed to be very easy to contribute to.

Every single page on the site is created from a Markdown file in the YS repository External link . This repo is a mono-repo, meaning that all parts of the YS project is in there.

Also, every page in the site (except the front page) has a "view source" button and an "edit this page" button. These buttons will take you to the source file for that page.

The "edit" button will drop you into the GitHub editor for that page. You can make your changes and then submit a pull request.

This is the easiest way to contribute to the site for small changes.

Bigger Changes🔗

If you want to add new pages of content, or make more significant changes, you should clone the repo and work on it locally. When you are ready to submit your changes, you can create a pull request.

Testing your changes locally is incredibly easy. To get started, run thesee commands:

$ git clone https://github.com/yaml/yamlscript
$ cd yamlscript
$ git checkout website  # PRs should be made against the "website" branch
$ cd www
$ make serve

The make serve command will install all the dependencies in the ./.venv/ and in /tmp/yamlscript/ and then start a local webserver at http://localhost:8000 External link .

It will aslo start a watcher that will automatically rebuild the site when you make changes to the source files. These changes will be visible in your browser immediately.

Important Source Files🔗

The YS website External link is built using the Material for MkDocs External link statis site framework, which is quite incredible in terms of what it can do (and easily).

Note

You don't need to know anything about MkDocs to make changes to the site, but if you want to add plugins or make theme customizations, you will need to learn a bit.

The prerequisites for building the site are very minimal:

  • Linux or MacOS
  • Python 3.6+
  • Python pip
  • GNU make
  • curl
  • bash

Note

The bash command just needs to be found in your PATH; it doesn't need to be your interactive shell. In other words, you can do development work on this site from from a terminal using zsh, fish, or whatever shell you prefer.

The most important files for the website are:

  • www/Makefile - This Makefile is used to handle all the various orchestration tasks you may need to do.
  • www/config.ys - The main configuration file for the site. Written in YS.
  • www/config/ - The YAML config files for various aspects of the site.
  • www/src/ - The source files for the site.
  • doc/ - The source files for the documentation.
  • blog/ - The source files for the blog.
  • www/requirements.txt - The Python requirements for the site.
  • www/theme/** - The theme override files for the site.

Ask Us for Help🔗

If you need help with anything, start a discussion here External link .