# Project page hosting on GitHub?

**URL:** <https://discourse.slicer.org/t/project-page-hosting-on-github/1563>\
**Category:** Project Week\
**Created:** [November 30, 2017, 2:46pm UTC](https://discourse.slicer.org/t/project-page-hosting-on-github/1563 "2017-11-30T14:46:10Z")\
**Posts on this page:** 20\
**Page:** 1

<div class="post-metadata">

**Author:** ![lassoan](https://sea2.discourse-cdn.com/flex002/user_avatar/discourse.slicer.org/lassoan/32/13_2.png) [@lassoan](https://discourse.slicer.org/u/lassoan)\
**Post date:** [November 30, 2017, 2:46pm UTC](https://discourse.slicer.org/t/project-page-hosting-on-github/1563/1 "2017-11-30T14:46:10Z")

</div>

I’ve ported a couple of intro pages and the current project week page from Slicer wiki to GitHub to show how we could use GitHub for project week page hosting:

Published website (using default blank theme): [https://na-mic.github.io/ProjectWeek/](https://na-mic.github.io/ProjectWeek/)

Example project page: [https://na-mic.github.io/ProjectWeek/PW27\_2018\_Boston/Projects/SlicerVR/](https://na-mic.github.io/ProjectWeek/PW27_2018_Boston/Projects/SlicerVR/)

Link for editing/uploading pages: [https://github.com/NA-MIC/ProjectWeek](https://github.com/NA-MIC/ProjectWeek)

Editable project template: [https://github.com/NA-MIC/ProjectWeek/blob/master/PW27\_2018\_Boston/Projects/Template/README.md](https://github.com/NA-MIC/ProjectWeek/blob/master/PW27_2018_Boston/Projects/Template/README.md)

Main advantages of GitHub:

- Full offline access. Entire wiki can be downloaded and viewed/edited on a laptop, without network access.
- Developer familiarity. All developers have GitHub account and familiar with how to upload and edit files.
- Uses Markdown, a very commonly used markup style (used for in the Slicer forum, GitHub, Slack, etc). MediaWiki markup is only used on MediaWiki sites.

Should we start using GitHub for hosting projects pages for this project week?

@Tina_Kapur @jcfr @pieper @ihnorton @cpinter @ungi

~~**EDITED:** Changed project name from `ProjectWeek` into `SlicerProjectWeeks`~~  
**EDITED #2:** Changed back to `ProjectWeek` to be inclusive and not focused on a specific platform.  
**EDITED #3:** Changed `27` to `PW27_2018_Boston`

---

<div class="post-metadata">

**Author:** ![fedorov](https://sea2.discourse-cdn.com/flex002/user_avatar/discourse.slicer.org/fedorov/32/14_2.png) [@fedorov](https://discourse.slicer.org/u/fedorov)\
**Post date:** [November 30, 2017, 6:11pm UTC](https://discourse.slicer.org/t/project-page-hosting-on-github/1563/2 "2017-11-30T18:11:52Z")

</div>

I agree there are many advantages moving away from the wiki. Another one to add to the list is that the process becomes much easier for new users to get an account and contribute content. It happened several times in my memory when users requested wiki accounts, but their request was misplaced, or took too long to approve.

I am struggling to think of disadvantages moving away from the wiki. Perhaps it is the ranking of the existing pages, but I would think that should be resolved with cross-linking.

However, I do not think web page is the right format. I would recommend GitBook. In addition to all of the advantages listed above:

- it supports hierarchical organization of the content
- content can be edited in a WYSIWYG editor, or directly in Markdown
- content can be contributed using either GitHub pull request, or direct edit of the content

See example here: [https://qiicr.gitbooks.io/dcmqi-guide/content/](https://qiicr.gitbooks.io/dcmqi-guide/content/). GitBook is also working on a new release, which has (in my view) further streamlined presentation (I have not spent a lot of time investigating the new one, just learned about it this week), see example of the same content on the new platform here: [https://qiicr.gitbook.io/dcmqi-guide/](https://qiicr.gitbook.io/dcmqi-guide/).

---

<div class="post-metadata">

**Author:** ![fedorov](https://sea2.discourse-cdn.com/flex002/user_avatar/discourse.slicer.org/fedorov/32/14_2.png) [@fedorov](https://discourse.slicer.org/u/fedorov)\
**Post date:** [November 30, 2017, 6:14pm UTC](https://discourse.slicer.org/t/project-page-hosting-on-github/1563/3 "2017-11-30T18:14:25Z")

</div>

I could put together an example of how this would look like on GitBook a bit later, if interested, so we can compare side by side…

---

<div class="post-metadata">

**Author:** ![lassoan](https://sea2.discourse-cdn.com/flex002/user_avatar/discourse.slicer.org/lassoan/32/13_2.png) [@lassoan](https://discourse.slicer.org/u/lassoan)\
**Post date:** [November 30, 2017, 7:58pm UTC](https://discourse.slicer.org/t/project-page-hosting-on-github/1563/4 "2017-11-30T19:58:31Z")

</div>

GitBook is just another html generator/hosting with some nice additional tools and it’s own Markdown flavor. We don’t need to decide on which generator(s) we will use, as we’ll host and edit Markdown files on GitHub anyway.

Last time we checked GitBook was not open to provide their service freely to a large number of users. Has anything changed?

In addition to GitBook, we may consider GitHub pages with various templates, Sphinx/ReadTheDocs, Reveal.js, etc. If we keep things simple then we can probably remain compatible with multiple generators.

---

<div class="post-metadata">

**Author:** ![lassoan](https://sea2.discourse-cdn.com/flex002/user_avatar/discourse.slicer.org/lassoan/32/13_2.png) [@lassoan](https://discourse.slicer.org/u/lassoan)\
**Post date:** [November 30, 2017, 8:02pm UTC](https://discourse.slicer.org/t/project-page-hosting-on-github/1563/5 "2017-11-30T20:02:18Z")

</div>

> [@fedorov](#):
>
> I could put together an example of how this would look like on GitBook a bit later, if interested, so we can compare side by side…

You can probably generate a gitbook from the current repository (maybe fork it so that you can experiment with what additional template and other files you have to add).

---

<div class="post-metadata">

**Author:** ![jcfr](https://sea2.discourse-cdn.com/flex002/user_avatar/discourse.slicer.org/jcfr/32/17825_2.png) [@jcfr](https://discourse.slicer.org/u/jcfr)\
**Post date:** [November 30, 2017, 9:57pm UTC](https://discourse.slicer.org/t/project-page-hosting-on-github/1563/6 "2017-11-30T21:57:48Z")

</div>

Well done 🙂

I like it.

Any objection in renaming the project to “slicer-project-week” or “SlicerProjectWeek” ?

> becomes much easier for new users to get an account and contribute content. It happened several times in my  
> memory when users requested wiki accounts, but their request was misplaced, or took too long to approve.

For the wiki, I think the idea was to avoid systematically granting access to everyone and explicitly authorize individual. We could change that and it will greatly streamline contribution. I start an other topic to discuss this.

The advantage of Github is that anyone can submit a PR without having anyone explicitly granting access before hand. This will indeed streamline the process.

---

<div class="post-metadata">

**Author:** ![lassoan](https://sea2.discourse-cdn.com/flex002/user_avatar/discourse.slicer.org/lassoan/32/13_2.png) [@lassoan](https://discourse.slicer.org/u/lassoan)\
**Post date:** [December 1, 2017, 2:22am UTC](https://discourse.slicer.org/t/project-page-hosting-on-github/1563/7 "2017-12-01T02:22:33Z")

</div>

> [@jcfr](#):
>
> Any objection in renaming the project to “slicer-project-week” or “SlicerProjectWeek” ?

I actually wanted to rename it to SlicerProjectWeeks but did not have the required access level. I think SlicerProjectWeeks is better than SlicerProjectWeek, as most likely we would host multiple project weeks in the same repository.

---

<div class="post-metadata">

**Author:** ![lassoan](https://sea2.discourse-cdn.com/flex002/user_avatar/discourse.slicer.org/lassoan/32/13_2.png) [@lassoan](https://discourse.slicer.org/u/lassoan)\
**Post date:** [December 1, 2017, 2:25am UTC](https://discourse.slicer.org/t/project-page-hosting-on-github/1563/8 "2017-12-01T02:25:09Z")

</div>

> [@jcfr](#):
>
> The advantage of Github is that anyone can submit a PR without having anyone explicitly granting access

We’ll have to see what works well in practice but we could grant write access to each person who submits a pull request with a meaningful project page. With protected branches it is quite safe to grant people write access, as it prevents accidentally overwriting the history. But I would expect that most people would directly edit the pages on the web GUI.

---

<div class="post-metadata">

**Author:** ![cpinter](https://sea2.discourse-cdn.com/flex002/user_avatar/discourse.slicer.org/cpinter/32/7995_2.png) [@cpinter](https://discourse.slicer.org/u/cpinter)\
**Post date:** [December 1, 2017, 3:09am UTC](https://discourse.slicer.org/t/project-page-hosting-on-github/1563/9 "2017-12-01T03:09:16Z")

</div>

> [@lassoan](#):
>
> With protected branches it is quite safe to grant people write access

In this page [About protected branches - GitHub Docs](https://help.github.com/articles/about-protected-branches) I read “Can’t be edited or have files uploaded to it from the web”. If it is still like this, then making it a protected branch would make it much harder to edit pages as every change would require a PR or git commit.

---

<div class="post-metadata">

**Author:** ![lassoan](https://sea2.discourse-cdn.com/flex002/user_avatar/discourse.slicer.org/lassoan/32/13_2.png) [@lassoan](https://discourse.slicer.org/u/lassoan)\
**Post date:** [December 1, 2017, 3:50am UTC](https://discourse.slicer.org/t/project-page-hosting-on-github/1563/10 "2017-12-01T03:50:53Z")

</div>

I’ve just tried and you can commit directly into a protected branch. I think protected branches got more sophisticated during the past years - you can set it up to only disable force push and delete of the branch.

---

<div class="post-metadata">

**Author:** ![fedorov](https://sea2.discourse-cdn.com/flex002/user_avatar/discourse.slicer.org/fedorov/32/14_2.png) [@fedorov](https://discourse.slicer.org/u/fedorov)\
**Post date:** [December 1, 2017, 4:42am UTC](https://discourse.slicer.org/t/project-page-hosting-on-github/1563/11 "2017-12-01T04:42:25Z")

</div>

> [@lassoan](#):
>
> GitBook is just another html generator/hosting with some nice additional tools and it’s own Markdown flavor. We don’t need to decide on which generator(s) we will use, as we’ll host and edit Markdown files on GitHub anyway.

Pure Markdown will not be sufficient, as we will need to adjust image sizes, insert videos etc. So some flavor of Markdown will be necessary. I don’t think flavors will migrate seamlessly across the various content management services you mentioned.

> [@lassoan](#):
>
> Last time we checked GitBook was not open to provide their service freely to a large number of users. Has anything changed?

What do you mean? If you mean large number of collaborators on a single book, then yes - that is constrained. We can apply for free next tier subscription, and that will increase the number of collaborators on a single book to 10. We did this for QIICR.

However, it that is not really critical, since GitBook content can be synchronized with a GitHub repo, which can follow conventional GitHub contribution workflow, and the GitBook automatically updated to track master or another selected branch. I think it should also be possible for other contributors to fork the GitHub repo, make a GitBook from that fork, edit content using visual editor on a specific branch, and then make a pull request back upstream.

---

<div class="post-metadata">

**Author:** ![jcfr](https://sea2.discourse-cdn.com/flex002/user_avatar/discourse.slicer.org/jcfr/32/17825_2.png) [@jcfr](https://discourse.slicer.org/u/jcfr)\
**Post date:** [December 1, 2017, 7:03am UTC](https://discourse.slicer.org/t/project-page-hosting-on-github/1563/12 "2017-12-01T07:03:25Z")

</div>

> [@lassoan](#):
>
> I actually wanted to rename it to SlicerProjectWeeks.

~~Repository renamed to `SlicerProjectWeeks` . See [https://na-mic.github.io/SlicerProjectWeeks/~~](https://na-mic.github.io/SlicerProjectWeeks/~~)

**EDITED:** Changed project name changed back to `ProjectWeek` so pages are available at [Welcome to the main page for the Project Week events! | NA-MIC Project Weeks](https://na-mic.github.io/ProjectWeek/)

> [@lassoan](#):
>
> but did not have the required access level.

Strange. You have “Owner” role within the NA-MIC GitHub organization.

> [@lassoan](#):
>
> We’ll have to see what works well in practice but we could grant write access to each person who submits a pull request with a meaningful project page. With protected branches it is quite safe to grant people write access, as it prevents accidentally overwriting the history. But I would expect that most people would directly edit the pages on the web GUI.

👍

> [@fedorov](#):
>
> we will need to adjust image sizes, insert videos etc

For youtube video, the preview picture could be added. See [here](https://stackoverflow.com/questions/4279611/how-to-embed-a-video-into-github-readme-md)

For adjusting image size, using `<img width="250px" src="https://url/to/image.png">` should work

---

<div class="post-metadata">

**Author:** ![pieper](https://sea2.discourse-cdn.com/flex002/user_avatar/discourse.slicer.org/pieper/32/8_2.png) [@pieper](https://discourse.slicer.org/u/pieper)\
**Post date:** [December 1, 2017, 1:35pm UTC](https://discourse.slicer.org/t/project-page-hosting-on-github/1563/13 "2017-12-01T13:35:22Z")

</div>

I suspect there will be a learning curve for the community no matter which method we pick. Hosting directly from github markdown pages seems the most “standard” and for that reason I think that people will derive the most educational benefit from getting familiar with the github process and github markdown, even if we have to live with some limitations (which so far seem fairly minor for our purposes).

---

<div class="post-metadata">

**Author:** ![lassoan](https://sea2.discourse-cdn.com/flex002/user_avatar/discourse.slicer.org/lassoan/32/13_2.png) [@lassoan](https://discourse.slicer.org/u/lassoan)\
**Post date:** [December 1, 2017, 2:39pm UTC](https://discourse.slicer.org/t/project-page-hosting-on-github/1563/14 "2017-12-01T14:39:42Z")

</div>

I agree. We can start with plain markdown syntax, it’s simple and compatible with everything. Once we gathered some initial experience, we can make much better informed decisions about how to improve things.

Has anybody talked to @Tina_Kapur? If she is OK with this, too, then we should announce that project pages should be created in this GitHub repository (and update the wiki page so that it points to the GitHub page).

---

<div class="post-metadata">

**Author:** ![jcfr](https://sea2.discourse-cdn.com/flex002/user_avatar/discourse.slicer.org/jcfr/32/17825_2.png) [@jcfr](https://discourse.slicer.org/u/jcfr)\
**Post date:** [December 1, 2017, 3:38pm UTC](https://discourse.slicer.org/t/project-page-hosting-on-github/1563/15 "2017-12-01T15:38:21Z")

</div>

Nitpick:

Instead of `27` as the name of the directory, should we follow a convention like `<Number>_<YYYY-MM>_<COUNTRY>_<CITY>`

For example:

```auto
25_2017-06_Italy_Calabria
27_2018-01_USA_Boston

```

---

<div class="post-metadata">

**Author:** ![ihnorton](https://sea2.discourse-cdn.com/flex002/user_avatar/discourse.slicer.org/ihnorton/32/9_2.png) [@ihnorton](https://discourse.slicer.org/u/ihnorton)\
**Post date:** [December 1, 2017, 4:27pm UTC](https://discourse.slicer.org/t/project-page-hosting-on-github/1563/16 "2017-12-01T16:27:55Z")

</div>

> [@jcfr](#):
>
> Instead of 27 as the name of the directory, should we follow a convention like \<Number\>_\<YYYY-MM\>_\<COUNTRY\>\_\<CITY\>

I think these are too long and annoying to type during the week – especially on mobile. So could we please at least set up [projectweek.slicer.org](http://projectweek.slicer.org) or even [pw.slicer.org](http://pw.slicer.org) as a redirect?

(I’m not sure why would these semantic URLs be useful? no one is going to remember how to type that, and google doesn’t care anyway 🙂 )

---

<div class="post-metadata">

**Author:** ![pieper](https://sea2.discourse-cdn.com/flex002/user_avatar/discourse.slicer.org/pieper/32/8_2.png) [@pieper](https://discourse.slicer.org/u/pieper)\
**Post date:** [December 1, 2017, 4:50pm UTC](https://discourse.slicer.org/t/project-page-hosting-on-github/1563/17 "2017-12-01T16:50:44Z")

</div>

The value of the semantic URL to me would be when you send or embed a link it would be easier to know in advance what you are linking to.

+1 to the idea of [pw.slicer.org](http://pw.slicer.org) as a redirect.

---

<div class="post-metadata">

**Author:** ![lassoan](https://sea2.discourse-cdn.com/flex002/user_avatar/discourse.slicer.org/lassoan/32/13_2.png) [@lassoan](https://discourse.slicer.org/u/lassoan)\
**Post date:** [December 1, 2017, 5:16pm UTC](https://discourse.slicer.org/t/project-page-hosting-on-github/1563/18 "2017-12-01T17:16:06Z")

</div>

> [@jcfr](#):
>
> 27\_2018-01\_USA\_Boston

In same cases more verbose, in other situations simpler, more predictable names are better.

Probably 27 is not trivial to interpret, while 27\_2018-01\_USA\_Boston is a bit too long to type. What about these?

- PW27
- PW27\_2018\_Boston
- PW27\_2018\_Jan\_Boston

---

<div class="post-metadata">

**Author:** ![cpinter](https://sea2.discourse-cdn.com/flex002/user_avatar/discourse.slicer.org/cpinter/32/7995_2.png) [@cpinter](https://discourse.slicer.org/u/cpinter)\
**Post date:** [December 1, 2017, 5:18pm UTC](https://discourse.slicer.org/t/project-page-hosting-on-github/1563/19 "2017-12-01T17:18:33Z")

</div>

I support finding some middle ground. My vote goes to PW27\_2018\_Boston, I think it’s not hard to remember even if you need to type it, and you’ll know when and where that project week was.

---

<div class="post-metadata">

**Author:** ![fedorov](https://sea2.discourse-cdn.com/flex002/user_avatar/discourse.slicer.org/fedorov/32/14_2.png) [@fedorov](https://discourse.slicer.org/u/fedorov)\
**Post date:** [December 1, 2017, 10:19pm UTC](https://discourse.slicer.org/t/project-page-hosting-on-github/1563/20 "2017-12-01T22:19:57Z")

</div>

I would definitely suggest [pw.na-mic.org](http://pw.na-mic.org). Branding project week with a specific platform can create various issues now and especially in the future. We should be inclusive, and think about possible issues down the road. I also think that this kind of decision should involve Ron. Monitoring updates from discourse can be cumbersome, and I suggest we should email Ron directly to seek his input.

[Next page](https://discourse.slicer.org/t/project-page-hosting-on-github/1563.md?page=2)