LearnOSM need to be tidy

[pyrog]

Hi,

One of the big problem is that this site is a… mess 😉

It use essentially _posts but this is not a blog, it's a book. We don't need to put chapters in _posts.
So the actually structure of learnOSM is too complicated, difficult to understand, translate and maintain.

We should tidy it and separate better data and code:

• data : chapters in .md format without liquid markup
• code: use "well" layouts and/or gems

Examples:

• All chapters code could be only in the layout
• same thing for Moving Forward
• Front matter are too complicated, we don't need:
  • permalink: if we will not use _posts
  • lang:, layout could determine it easily from the page.path 😉
  • category: same as permalink.
• Images:
  • their names are too complicated
  • some of them should translated, internationalized
    (so we should have the source image and separately the anotations written on them)
• layouts are too complicated:
  • a layout could call another one. Hi levels layout represent structures (menu, header, footer, traffic analysis Web Traffic Analytics? #294, …), low levels contains HTML
  • a layout could also include other files

[pyrog]

You could have a look to the result : http://pyrog.github.io/learnosm-sandbox/en/
The Jekyll source code is here : https://github.com/pyrog/learnosm-sandbox

Note: the german page about is missing to check what happened when a page is untranslated (see #252)

[wonderchook]

Hi @pyrog if I understand you are saying "tidy" to mean two different things?

1. File structure behind the site
2. Design of the site

I don't see there being a lot of different simple moving the files out of the "_posts" they are already in there in individual language folders. There could be better organization within there.

As for the resulting site you created I'm a big confused, it looks like a default Jekyll site. The LearnOSM site as it was done now was created with a design process and I think is a modern site and a good look.

[pyrog]

• Mostly tidy file structure behind the site 😄
• For the "design" I mean "coding design", not "graphical design".
  For example, if we want to add a feature like "Next chapter" (see link or button to the next page or next section #270), the changes should be done only once by devs, to avoid editing all page.md (and probably forget some).

As for the resulting site you created […] it looks like a default Jekyll site.

Of course, I use the default template 😉
I would prove that _posts are not mandatory, because the official Jekyll documentation is not very clear:

page.url
The URL of the Post without the domain, but with a leading slash, e.g.  /2008/12/14/my-post.html

[althio]

Hi @wonderchook
@pyrog wants to help only with the structure, not the graphical design.
The staging site he presented is only a proof-of-concept to show that jekyll can handle something else than blog structure. Little step I know, but step by step... :)

It is also an available sandbox where we can test anything around structure.
But -- you are right -- it is not intended as a proposal for graphical design and look.

I don't see there being a lot of different simple moving the files out of the "_posts" they are already in there in individual language folders. There could be better organization within there.

Generally (in issues+sandbox+discussion+lists...) we would like to assess the pros and cons of blog structure and regular structure.
The regular structure might be more adapted to handle organised and hierarchical content like ours instead of chronological content like a blog.

As it stands with the _posts folder, category organisation, dated and ordered filenames... It looks slightly odd and we are trying to understand the current implementation as blog. My feeling (for the time being!) is that it is not completely suited and requires a bit of shoehorn. I would like to know more about the history and previous choices. I would love to get critical feedback on any structure.

[pyrog]

The regular structure might be more adapted to handle organised and hierarchical content like ours

With the suggested design, it will simpler and obvious 😄 :

• source file structure = static file structure
• source filenames = static file names
• no need to add/edit permalink: in each files front matter

So currently we have for the file /fr/beginner/moving-forward.html

His jekyll source filename:

/_posts/fr/beginner/0200-12-21-moving-forward.md

His frontmatter:

---
layout: doc
title: Pour aller plus loin
permalink: /fr/beginner/moving-forward/
lang: fr
category: beginner
otherguides: "Les autres niveaux"
---

After the tidying of Mr Clean 😉:

/fr/beginner/moving-forward.md

Is front matter will be:

---
layout: doc
title: Pour aller plus loin
category: beginner
otherguides: "Les autres niveaux"
---

[pyrog]

Tidying images:

In the images folder, many images are redundant:

• a flat file structure LC_GUIDE_CHAPTER_imageXX.png
  ie. en_beg_ch8_image00.png
• another one CHAPTER_imageXX_LC.png
  i.e.. start_josm_image01_en.png
• a file structure LC/GUIDE/XX_CHAPTER/LC_GUIDE_XX_CHAPTER_imageXX_TITLE.png
  ie. en/beginner/01_introduction/en_beg_01_introduction_image00_village-in-indonesia.png
• a lot (all??) the images are not localized (fr, de, es… images are the same than en images)
• inside .md files, two markdown syntax are used to display an image:
• inside .md files, two markdown syntax are used to display an image:

![paper scanned][]
…
[paper scanned]: /images/en/beginner/06_field-papers/en_beg_06_field-papers_image20_watchsnapshot.png

![image](/images/fr/0300-12-23-private-data-store/image19.png)

With the regular expression below, I found only 1 796 images used by .md files in _posts/

!\[\w*\]

The regexp found images like:

![image20][]
![]({{site.baseurl}}/images/en/intermediate/en_int_ch6_image14.png)

If I search only in the _posts/en folder, only 236 are really used !!

Finally, there is 3 036 images in the folder images !!

[Nick-Tallguy]

@pyrog thanks for your work on this. I'm no expert, but reading through what you are proposing, it looks as if we would have a far easier to understand 'filing system' for the files needed to display the site if we adopted it.
I know that I found it a bit of a headache working out what to use as the header on .md files - I can't say as I understand it now, I just know how to make it work, but the logic of it seems to defeat me - comments about a blog make more sense when I look at the system we currently have.
I've looked through, but can't see where & how images would be filed? (If they end up in the same folder as the .md file, this could simplify pdf production for some of the software I've looked at.)

I'd be interested to see what the proposal would be for a transition - How easy would it be to change from one filing system to another, and would the site be available throughout? The site is constantly being updated, so a transfer would get a little complicated. I'm guessing we could branch, change the structure in the branch, alter the file which shows the web address, and if there is a problem quickly change back until it is sorted - the proposed site can be viewed on jekyll when being 'built' - need the advice of someone with more knowledge though.

My own level of knowledge is such that I would not attempt to start something like this proposal unless there were assurances from users such as yourself who understand how this should work, that they would stay with the project & help with ironing out any glitches.

Whatever system we end up with needs better documentation of 'howto' for those who are willing to write articles about mapping, HOT, etc., than we currently have. For the future, and those who follow on from us, it would be good to have a more logical system so mappers who wish to help others can easily write articles & submit them for inclusion.

Could the change over be managed incrementally?

I am concerned that the amount of effort involved could outweigh the benefits - I need someone with more knowledge on the subject to offer advice so we could then discuss & decide what to do.

[pyrog]

I've looked through, but can't see where & how images would be filed?

Where you want inside the project tree 😉

(If they end up in the same folder as the .md file, this could simplify pdf production for some of the software I've looked at.)

I just made a test and it works 😄

In /en/beginner/introduction.md

![A village in Indonesia](images/village-in-indonesia.png)

But if you want to use the same image from the french translation, it could be tricky:

• ![Un village en Indonésie](images/village-in-indonesia.png) don't work 😞
• ![Un village en Indonésie](/en/beginner/images/village-in-indonesia.png) work 😄

The simplest solution for editors is to choose the first one, but dev need to:

1. add a symlink from /fr/beginner/images → /en/beginner/images, or
2. write a plugin that automatically fix the image url if it is missing in the "local" folder
3. use a redirection mechanism in 404 layout ? (no tested)

Example for case 2.

In /fr/beginner/introduction.md

![A village in Indonesia](images/village-in-indonesia.png)

1. search for /fr/beginner/images/village-in-indonesia.png
2. found nothing
3. replace fr by en /en/beginner/images/village-in-indonesia.png

Currently, I use the KIS method : /images/beginner/village-in-indonesia.png

If an image should be localized, I suggest to add the language code in the prefix:

• /images/beginner/save-button.png (for the english page)
  
• /images/beginner/save-button.fr.png (for the french page)
  

[pyrog]

I'm guessing we could branch, change the structure in the branch, alter the file which shows the web address, and if there is a problem quickly change back until it is sorted

Yes, it's easy with git and github