Lesson organisation doesn't reflect URL of home page on GitHub

[gcapes]

Re: http://carpentries.github.io/lesson-example/03-organization/index.html

The diagram here reflects what is in the _site folder, but the home page (created from index.md) as clicked from the Lesson Title header from any episode, or from the github repo page is http://carpentries.github.io/lesson-example/ rather than http://carpentries.github.io/lesson-example/index.html.

This makes the diagram more difficult to interpret, because although the two URLs are equivalent, the one that is normally seen doesn't include index.html

[gcapes]

The same applies for setup.md

[maxim-belkin]

I'm not sure I understand the confusion. Navigating to https://website.com is equivalent to navigating to https://website.com/index.html (or https://website.com/default.html or https://website.com/home.html). So the point that diagram is trying to make is that every file is converted to a directory with index.html in it.

[gcapes]

Navigating to https://website.com is equivalent to navigating to https://website.com/index.html

In general, this isn't true. Consider https://www.bbc.co.uk/news. Now try https://www.bbc.co.uk/news/home.html --- it gives a 404 error.

For the purposes of the lessons, navigating to http://swcarpentry.github.io/lesson/ is the same as http://swcarpentry.github.io/lesson/index.html but how are contributors supposed to know this? This is the confusion.

The reverse is true for the episodes: navigate to an episode and the URL is http://swcarpentry.github.io/lesson/01-intro/index.html. This is consistent with the description in episode 3. However, that this URL is equivalent to http://swcarpentry.github.io/lesson/01-intro/ isn't documented, and wasn't at all obvious to me.

I would suggest using the default URLs, or at least indicating the equivalence.

[brownsarahm]

Maybe the issue isn't so much that the diagram is difficult to interpret but that its scope is only to explain the file structure, not URLs at all? Someone with near zero knowledge of web development might not even know enough to be confused. I would say the diagram is fine if the scope of it is to explain the file structure, which is what the text around it suggests. We could add a section on URLs to help people know what to expect in terms of URLs.

Relatedly, is there a specific case contributors need to understand how the URLs work? If so, we should take care to explain that. I think in general, the design doesn't expect people to be writing those URLs into things.

[maxim-belkin]

Navigating to https://website.com is equivalent to navigating to https://website.com/index.html

In general, this isn't true. Consider https://www.bbc.co.uk/news. Now try https://www.bbc.co.uk/news/home.html --- it gives a 404 error.

You specified the file you're interested in -- home.html -- and BBC website doesn't have that. I was talking about specifying a URL without a file name, in which case this is up to the web server to decide which file to serve you. Usually, web servers serve index.html (or index.php, or index.htm) but they could just as well serve you any other file(default.html, home.html).

[gcapes]

Ok, let me try again.

Someone wants to edit a page of a SWC lesson. All they know about the page is the URL. They fork the repo, and want to know which file to edit. How do they find out? There doesn't appear to be an easy way.

The diagram shows how markdown files relate to the html files in _site. Assume the contributor knows as little about web stuff as I do, but they know the URL of the page is: http://carpentries.github.io/lesson-example/03-organization/index.html They can follow the diagram working backwards to see that this corresponds to _episdoes/03-organisation.md. So far so good, because the _site folder maps onto the URL nicely.

Now assume they want to edit the file used to make this page: http://carpentries.github.io/lesson-example/setup.html There is nothing that corresponds. The diagram shows that setup.md makes a file called setup/index.html, and this is confusing because the file it actually makes is _site/setup.html, not _site/setup/index.html --- so the diagram is wrong --- and the end of the URL (which is all the contributor knows for sure) doesn't match up with the diagram either. This confusion also applies to code of conduct, and licence.

[brownsarahm]

This description is helpful @gcapes!

Re: the setup page there is definitely an error, several pages now do not work the way that diagram suggests, so should either update the diagram or make them work the way it says they do (setup, license, code of conduct). If we update the diagram we should also change reference to behave the same way, for consistency. I think the pattern of folders is better and we should fix the infrastructure to work the way this diagram says it should. In which case this would actually be an issue for styles, somone with admin can move the issue if they agree and then a PR can happen there? @fmichonneau thoughts?

semi-related, at least the two lessons I looked at actually have discuss in _extra, not discussion, but this may not be important?

For the episodes, I think adding text below the diagram that makes explicit that the pattern folder/index.html can render to multiple URLS would address the remaining concern? And this would be a change here on lesson-example

[maxim-belkin]

We need to look into this more closely because setup pages are not super consistent (see below). The two repositories that have /setup/index.html have the following in their setup.md:

permalink: /setup/
root: ..

→ https://swcarpentry.github.io/python-novice-inflammation/setup/index.html B https://swcarpentry.github.io/shell-novice/setup.html B https://swcarpentry.github.io/r-novice-inflammation/setup.html B https://swcarpentry.github.io/git-novice/setup.html B https://swcarpentry.github.io/r-novice-gapminder/setup.html B https://swcarpentry.github.io/make-novice/setup.html B https://swcarpentry.github.io/matlab-novice-inflammation/setup.html → https://swcarpentry.github.io/python-novice-gapminder/setup/index.html B https://datacarpentry.org/python-ecology-lesson/setup.html B https://datacarpentry.org/cloud-genomics/setup.html B https://datacarpentry.org/organization-geospatial/setup.html B https://datacarpentry.org/shell-genomics/setup.html B https://datacarpentry.org/python-socialsci/setup.html

As for the LICENCE.md, here is what I see in python-novice-inflammation:

commit 95644a91f9be4793d084125e5665c5aa50f221c7
Author: Raniere Silva <[email protected]>
Date:   Tue Nov 7 16:30:34 2017 +0000

    Fix root YAML variable in bin/lesson_initialize.py
    
    Close #186

diff --git a/LICENSE.md b/LICENSE.md
index 179758a..e107599 100644
--- a/LICENSE.md
+++ b/LICENSE.md
@@ -1,7 +1,7 @@
 ---
 layout: page
 title: "Licenses"
-permalink: /license/
+root: .
 ---
 ## Instructional Material

and for CODE_OF_CONDUCT.md:

commit 986a6beb7b03c1dfee0247ea3bbc5036689afb8d
Author: Michael R. Crusoe <[email protected]>
Date:   Wed May 30 12:16:56 2018 +0300

    remove permalink that breaks asset includes
    
    Will also match https://raw.githubusercontent.com/swcarpentry/lesson-example/gh-pages/CONDUCT.md

diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
index acf6fb6..c3b9669 100644
--- a/CODE_OF_CONDUCT.md
+++ b/CODE_OF_CONDUCT.md
@@ -1,7 +1,6 @@
 ---
 layout: page
 title: "Contributor Code of Conduct"
-permalink: /conduct/
 ---
 As contributors and maintainers of this project,
 we pledge to follow the [Carpentry Code of Conduct][coc].