This Git repository holds the source code for the csound.github.io website, found at https://csound.com. The source is made up of Markdown (.md) files, which hold the content for pages and posts. These files are further processed by Jekyll, together with template files, to generate the final HTML site.
This site is an open-source, collaborative project. The Csound community is encouraged to contribute to the maintenance of the site by adding news posts, modifying pages, updating the structure of the site, and developing the style of the pages. The following describes how to perform these tasks. These tasks may be performed directly by members of the site maintainers team, or indirectly via pull request by third parties.
Users who would like to contribute, but who are not comfortable with the technical details to make a direct contribution, are encouraged to either file an issue on the issue tracker describing the news entry or requested change, or contact one of the site maintainers who will work to evaluate and integrate any changes.
Edit _data/download.yaml.
In case you want to add a new download item, add it in _data/download.yaml and edit _layouts/download.html.
It is always most easy to use an existing post, save it with a new name and modify it.
News are located in the _posts folder.
Projects are located in the \posts/showcase folder.
Each post must have a header that states the title, categories, layout, and date of the post. After the header, the post is written using Github Flavored Markdown text.
Add the image file (.png or .jpeg) in the /images folder.
To show the image, you have two possibilities:
- You can use the markdown syntax for images:
 - It might be better to use html and include Bootstrap's "img-fluid" class to make the image responsive and optionally scale it:
<img src="images/ADSR.png" class="img-fluid" alt="ADSR" width=75% />
To add Csound syntax highlighting to a code block, start with
```csound
and end the block with three backticks
```
Pages are also Markdown files. They require headers that specify the layout (most should use "page") and title.
The pages markdown files follow the site structure:
- get-started.md and others are in the /learn folder
- conferences.md and others are in the /community folder
New pages can be made by copying one of the existing pages and updating it for the new content. Add an item at _data/navigation.yaml.
Existing pages may be modified locally and pushed to the repository, or submitted as a change via pull request. Pages may also be modified directly through the GitHub project site, which allows modifying the page within the browser. Users can navigate to the file in the project, select the edit button, then finish the edit.
In general there are three options for links:
- Relative links, for instance in _/layouts/home.html we can reference
href="get-started.html"as relative link because whenever we are in home, we are on the same directory as the get-started.html which is generated by jekyll. - We avoid absolute URL because they will not work if we test on a github projects page. (myname.github.io/myproject as root will give an error for the link '/home.html' because the page cannot be found at myname.github.io/home.html but at myname.github.io/myproject/home.html.)
- This is the reason we use the version href="{{ '/contact-us.html' | relative_url }}" instead, for instance in _include/footer.html. No matter where the current site is, it will look for contact-us.html in the root directory of the relative URL.
This folder contains the most recent version of the manual and other references. Never change its name. (As well not for any existing page; otherwise you will create dead links.)
The site uses Bootstrap 5 and a modified template by Saul Roll. The Bootstrap CSS should not changed at all; it can be replaced by a more recent version if necessary.
Syntax highlighting is done via rainbow. The source files live in assets/css/highlight and assets/js/highlight.
Font-Awesome is used for some icons, too.
Changes in styling must go to csound.site.css. These two style sheets are referenced in "default.html" in this order, so that Bootstrap settings are overwritten by our own styles.
The code is in _layouts/home-html. It is easy to change a carousel item.
Images for the landing page (carousel) must have 1140 width and 620 height as size.
- Ruby
- RubyGems - most ruby distributions should come with gem installed
- Bundler - install using
gem install bundler
First, make a clone of the project locally:
git clone https://github.com/csound/csound.github.io.git
cd csound.github.io
From this directory, run Bundler to install the required gems:
bundle install
This installed the github-pages gem.
To view the site locally with jekyll, run:
bundle exec jekyll serve
This will start up a jekyll server. You can view the pages as they are rendered by Jekyll in your browser at:
http://localhost:4000