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.:warning: Preview is only available for pull request originating from this repository. |
Preview for download.slicer.org maintenance page | Preview of download.slicer.org automatically associated with target branch deploy-download-maintenance-preview.:warning: Preview is only available for pull request originating from this repository. |
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 git@github.com:yourname/slicer.org
Update files in the directory slicer.org
with you proposed changes.
Prepare the build environment creating the gh-pages
docker image
git clone git@github.com:github/pages-gem.git
cd pages-gem
make image
For more details, see https://github.com/github/pages-gem#docker
"Run" the build environment by shelling into the the gh-pages
docker 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.
_config.yml
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
_config_dev.yml
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.
_config_download.yml
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
.
_config_download_maintenance.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
.
index.markdown
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
_data
directoryLearn more at https://jekyllrb.com/docs/datafiles/
_data/footer-site-map.yml
Describes the links used to generate the top-level navbar and footer entries.
_data/solutions.yml
List of solutions used to generate main section, navbar and footer entries
_layout/*.html
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/
_includes/*.html
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/
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: