The slicer-org branch of this repository stores the files deployed at https://slicer.org.
The site is implemented using jekyll static site generator and uses the Bulma clean theme.
The site is implemented using jekyll static site generator and uses the Bulma clean theme.
Each time the sources of the static site organized in the main branch are updated, the following branches are automatically updated using the GitHub Action workflow described in .github/workflows/build-website.yml:
These branches are automatically pulled into their respective live sites. There is no need to connect to the server in order to make changes.
| Branch | Site | Frequency | Jekyll build configuration |
|---|---|---|---|
| slicer-org | Deployed to https://slicer.org | 5 mins | --config _config.yml |
| download-slicer-org | Deployed to https://download.slicer.org | 5 mins | --config _config.yml,_config_download.yml |
This branch is expected to be manually pulled into the download server.
To update the maintenance page, edit _config_download_maintenance.yml and submit a pull-request.
| Branch | Jekyll build configuration |
|---|---|
| download-maintenance-slicer-org | --config _config.yml,_config_download.yml,_config_download_maintenance.yml |
| Link | Description |
|---|---|
| Deploy Previews for slicer.org | Preview of slicer.org site automatically associated with pull requests. |
| Preview for download.slicer.org | Preview of download.slicer.org automatically associated with target branch deploy-download-preview. |
| Preview for download.slicer.org maintenance page | Preview of download.slicer.org automatically associated with target branch deploy-download-maintenance-preview. |
To learn more about Netlify preview, see here.
The netlify deployment has been configured by @jcfr and since the free plan is being used, only one user can update its configuration.
The website builds associated with these branches are also uploaded as GitHub Action artifacts:
-
Edit file and create a pull request directly from your browser. See details.
The following instructions assumes you have docker installed. On Windows, you may use Git Bash.
-
Fork this repository. We will assume your GitHub account is yourname.
-
Download the static content (Make sure to replace yourname):
git clone [email protected]:yourname/slicer.org -
Update files in the directory
slicer.orgwith you proposed changes. -
Prepare the build environment creating the
gh-pagesdocker imagegit clone [email protected]:github/pages-gem.git cd pages-gem make imageFor more details, see https://github.com/github/pages-gem#docker
-
"Run" the build environment by shelling into the the
gh-pagesdocker image.cd /path/to/slicer.org docker run -ti --rm \ -p 4000:4000 \ -v `realpath .`:/src/site \ gh-pages bash -
Generate and serve the website
bundle install git config --global --add safe.directory /src/site config_opts=_config.yml,_config_dev.yml # For slicer.org #config_opts=_config.yml,_config_download.yml,_config_dev.yml # For download.slicer.org #config_opts=_config.yml,_config_download.yml,_config_download_maintenance.yml,_config_dev.yml # For download.slicer.org maintenance page rm -rf /_site/* bundle exec jekyll serve \ -d /_site --config ${config_opts} \ --watch \ --force_polling \ -H 0.0.0.0 -P 4000 \ --incremental -
Open http://localhost:4000 with your favorite browser. Edit the files until your are satisfied with the result.
-
Publish your branch and create a pull request
This section described files and directories used by the static site generator.
The _config.yml file contains settings that Jekyll uses as it processes the site and generate the slicer.org site.
See _config.yml and https://jekyllrb.com/tutorials/convert-site-to-jekyll/#what-is-a-jekyll-website
The _config_dev.yml file sets url and slicer_download_url using http://localhost:4000.
It is should only be specified in addition of any other files when developing locally.
The _config_download.yml file contains settings used to generate the download.slicer.org site.
It is should be specified in addition of _config.yml.
The _config_download_maintenance.yml file contains settings used to generate the download site with a banner indicating
that the regular downloads are not available and will be available soon.
See _config_download_maintenance.yml
It is should be specified in addition of _config.yml and _config_download.yml.
This document describes the properties used to generate the website main page.
It includes the following sections:
| Name | Properties |
|---|---|
| Hero | Title, subtitle and list of buttons used in top-level section |
| About | Title, subtitle and description for the What is 3D Slicer section |
| Carousel | List of images and associated descriptions |
| Features | List of features including title, subtitle and description of the section |
| Solutions | Title, description and properties common to all solution. See _data/solutions.yml for the list. |
| Commercial Use | Title, subtitle and description of the section |
| Communities | Title, subtitle and description of the section |
See index.markdown
Learn more at https://jekyllrb.com/docs/datafiles/
Describes the links used to generate the top-level navbar and footer entries.
List of solutions used to generate main section, navbar and footer entries
Layouts are templates that can be used by any page in your site and wrap around page content.
See _layout
Learn more at https://jekyllrb.com/docs/step-by-step/04-layouts/
The include tag allows you to include content from another file stored in an _includes folder. Includes are useful for having a single source for source code that repeats around the site or for improving the readability.
See _includes
Learn more at https://jekyllrb.com/docs/step-by-step/05-includes/
- Commercial Use
To add an internal site pages, create a markdown file with a front matter.
For example, see commercial-use.markdown
- Use page layout in you markdown header:
layout: page
- To add side menu on your page create a .yml file for the menu under _data folder and use it in markdown header like this:
menubar: example_menu
- To add table of contents on your page use it in markdown header like this:
toc: true
- To add sidebar on your page use it in markdown hear like this:
show_sidebar: false
The configuration file favicon.json was originally generated using https://realfavicongenerator.net/ and uploading 3D-Slicer-Mark.svg.
Step-by-step:
-
Review and update
favicon.json -
Execute the following commands:
npx cli-real-favicon generate favicon.json faviconData.json assets/favicons/Note: npx command-line is available after installing node
-
Update _includes/head.html based on content of the generated file
assets/favicons/README.md -
If missing, add front matter to assets/favicons/browserconfig.xml
---
layout: null
---
-
If if applies, remove the extra
?v=...from assets/favicons/site.webmanifest -
Remove extraneous files
rm faviconData.json
rm assets/favicons/README.md
rm assets/favicons/apple-touch-icon-*.png- Commit changes
git add favicon.json assets/favicons/* _includes/head.html
git commit -m "ENH: Update favicons"Transition to GitHub for managing and serving the Slicer top level page was discussed on Slicer Discourse forum. See https://discourse.slicer.org/t/its-all-about-transitions-lets-talk-about-slicers-landing-page
It is covered by the Slicer License: