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.

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

Go to https://github.com/slicer/slicer.org
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.

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

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:

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"

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

Overview

Table of Contents

Infrastructure

Production

Automatic Deployment

Maintenance

Preview

Netlify

Website build

Development

Development Using GitHub UI

Local Development

Source Files

`_config.yml`

`_config_dev.yml`

`_config_download.yml`

`_config_download_maintenance.yml`

`index.markdown`

`_data` directory

`_data/footer-site-map.yml`

`_data/solutions.yml`

`_layout/*.html`

`_includes/*.html`

Internal pages

Useful links

Adding an internal page

Regenerating favicons

History

License

Files

README.md

Latest commit

History

README.md

File metadata and controls

Overview

Table of Contents

Infrastructure

Production

Automatic Deployment

Maintenance

Preview

Netlify

Website build

Development

Development Using GitHub UI

Local Development

Source Files

_config.yml

_config_dev.yml

_config_download.yml

_config_download_maintenance.yml

index.markdown

_data directory

_data/footer-site-map.yml

_data/solutions.yml

_layout/*.html

_includes/*.html

Internal pages

Useful links

Adding an internal page

Regenerating favicons

History

License

`_config.yml`

`_config_dev.yml`

`_config_download.yml`

`_config_download_maintenance.yml`

`index.markdown`

`_data` directory

`_data/footer-site-map.yml`

`_data/solutions.yml`

`_layout/*.html`

`_includes/*.html`