Overview

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.

Table of Contents

• Overview
• Infrastructure
  • Production
    • Automatic Deployment
    • Maintenance
  • Preview
• Development
  • Development Using GitHub UI
  • Local Development
  • Source Files
  • Useful links
  • Adding an internal page
  • Regenerating favicons
• History
• License

Infrastructure

The site is implemented using jekyll static site generator and uses the Bulma clean theme.

Production

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:

• slicer-org
• download-slicer-org
• download-maintenance-slicer-org

Automatic Deployment

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

Maintenance

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

Preview

Netlify

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 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. ⚠️ 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.

Website build

The website builds associated with these branches are also uploaded as GitHub Action artifacts:

• slicer-org
• download-slicer-org
• download-maintenance-slicer-org

Development

Development Using GitHub UI

1. Go to https://github.com/slicer/slicer.org

2. Edit file and create a pull request directly from your browser. See details.

Local Development

The following instructions assumes you have docker installed. On Windows, you may use Git Bash.

1. Fork this repository. We will assume your GitHub account is yourname.

2. Download the static content (Make sure to replace yourname):

   git clone git@github.com:yourname/slicer.org
   

3. Update files in the directory slicer.org with you proposed changes.

4. 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

5. "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
   

6. 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
   

7. Open http://localhost:4000 with your favorite browser. Edit the files until your are satisfied with the result.

8. Publish your branch and create a pull request

Source Files

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.

See _config_download.yml

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 directory

Learn 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.

See _data/footer-site-map.yml

_data/solutions.yml

List of solutions used to generate main section, navbar and footer entries

See _data/solutions.yml

_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/

Internal pages

• Commercial Use

See commercial-use.markdown

Useful links

• Bulma documentation
• Bulma clean theme documentation
• Jekyll static site generator

Adding an internal page

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

Regenerating favicons

The configuration file favicon.json was originally generated using https://realfavicongenerator.net/ and uploading 3D-Slicer-Mark.svg.

Step-by-step:

1. Review and update favicon.json

2. Execute the following commands:

npx cli-real-favicon generate favicon.json faviconData.json assets/favicons/

Note: npx command-line is available after installing node

3. Update _includes/head.html based on content of the generated file assets/favicons/README.md

4. If missing, add front matter to assets/favicons/browserconfig.xml

---
layout: null
---

5. If if applies, remove the extra ?v=... from assets/favicons/site.webmanifest

6. Remove extraneous files

rm faviconData.json
rm assets/favicons/README.md
rm assets/favicons/apple-touch-icon-*.png

7. Commit changes

git add favicon.json assets/favicons/* _includes/head.html
git commit -m "ENH: Update favicons"

History

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

License

It is covered by the Slicer License:

https://github.com/Slicer/slicer.org/blob/main/LICENSE