This Git repository holds the source code for the csound.github.io website, found at http://csound.github.io. 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.
How to contribute
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.
Adding a News post
News posts are created using Markdown files placed in the _posts folder. Each post must have a header that states the title, categories, layout, and date of the post. (For news, the layout should be "post".) After the header, news is written using standard Markdown text. Images and other content may be put into the post by using standard HTML content (i.e. for images, use the image tag). The actual image should be placed in the images folder. If you have a question, it may help to look at one of the existing posts to use as a reference.
Modifying and Creating Pages
Pages are also Markdown files. They require headers that specify the layout (most should use "default") and title. Top-level pages are found in the root of the Git repository. Pages may also be placed in sub-folders. The pages must be linked to in some way for users to access them. This is generally done by modifying one of the templates in the _templates or _includes 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/cms.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.
Modifying the site structure
The structure of the site is organized through the links of the navigation. The links are placed in the _templates and _includes so that they are shared by all pages and posts. To modify the structure, update one of the template files.
Modifying the site theme
The site currently uses Bootstrap as the foundation for its theme. Site maintainers are free to continue using Bootstrap or replace it should they find a better solution.
Editing the Site Locally
- 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 git://github.com/csound/csound.github.io.git cd csound.github.io
From this directory, run Bundler to install the required gems:
This installed the github-pages gem.
To view the site locally with
bundle exec jekyll serve -I
This will start up a jekyll server. You can view the pages as they are rendered by Jekyll in your browser at:
Also, with the -I flag, anytime you change a page, you can view the updates by refreshing the browser.