Create FAQ markdown

[Lineflyer]

Once created I volunteer to fill it based on the existing FAQ if it is a markdown file (maybe prefilled with a placeholder to understand the needed markdown syntax).

Just copying might not be enough as some items might be outdated (last general update was done some months ago), so I would like to update while transfering it.

[SammysHP]

Good idea to update it!

There are two possibilities:

• Markdown, only conversion to HTML
• YAML, create dynamic output via templates

[Lineflyer]

As I have no idea about the difference of these two possibilities I would prefer the one which is more straight forward to edit later on.

[SammysHP]

Yesterday I've pushed a new experimental branch for this:
https://github.com/cgeo/cgeo.github.io/tree/faq

Today I had a new idea: Don't use a single YAML file, but one file per faq entry organized in folders.

_data
└── faq
    ├── category1
    │   ├── meta.yml
    │   └── items
    │       ├── faq1.yml
    │       ├── faq2.yml
    │       └── faq3.yml
    ├── category2
    │   ├── meta.yml
    │   └── items
    │       ├── faq1.yml
    │       ├── faq2.yml
    │       └── faq3.yml
    └── category3
        ├── meta.yml
        └── items
            ├── faq1.yml
            ├── faq2.yml
            └── faq3.yml

They will be sorted by filename (but I need to test this first) and each faq will be like

title: Title of the FAQ entry
id: some_string
content: |
    This is the content of the FAQ entry

Reason for ID: Currently the anchor is generated from the index of the item. So when you insert another FAQ entry in the middle the IDs will change. This is bad. With this ID you'll get a permalink that won't change.

I'll test this today or tomorrow.

[samueltardieu]

Why not build the ID automatically from the title? If the title changes, the ID should also change.

[SammysHP]

Should be possible: https://github.com/shopify/liquid/wiki/liquid-for-designers#standard-filters

[SammysHP]

Implementation with multiple files:
https://github.com/cgeo/cgeo.github.io/tree/faq2

I'm not happy with it.

[Lineflyer]

@SammysHP DId you come to a conclusion with your different approaches?

[SammysHP]

Not yet. I have only very little time in the next weeks (exams) and hope that some of you have good ideas and improvements for my drafts so that someone can make it better and merge it.

[Bananeweizen]

If I get it right, the question here is just whether to use a single file or multiple files. As you said you may not have time, I suggest that we simply merge one of the two alternatives, even if we cannot fully estimate the different pros and cons. I can't judge, but if no one raises another opinion, then I will merge the first single file approach at the weekend.

Reason is that I want to enable all of us to continue the writing of the FAQ. We can later still refactor to another approach, should that be necessary.

PS: I could not try it locally. The installation of the ruby stuff already breaks on my Ubuntu system...

[SammysHP]

Independent of the version (single vs multiple files) we should use at least the style of the second implementation as it is much better (but still far a way from nice).

[SammysHP]

I've merged the first (single file) implementation with some improvements. Please test and improve.

@Lineflyer
I've extended the README and explained how the FAQ is edited. You can start now with your work. :) Reassigning.

[Lineflyer]

Thanks, I started looking into it and experimented already in my fork.

One question regarding the syntax:
Is it possible to insert a linefeed without creating a space in between (and not having the blockquote in the first line).

Here: https://github.com/Lineflyer/lineflyer.github.io/blob/master/_data/faq.yml

I want:

You can also manually select your preference in c:geo settings:
Menu button - Settings - Appearance - "Use Imperial units"

but I get either (with linefeed):

You can also manually select your preference in c:geo settings:

Menu button - Settings - Appearance - "Use Imperial units"

or (if I remove the linefeed):

You can also manually select your preference in c:geo settings: Menu button - Settings - Appearance - "Use Imperial units"

[Lineflyer]

Regarding the process of migrating the FAQ:
I volunteer (as said abbove) to first of all take over all existing chapters and in parallel update/rework/remove them as needed and push it to master piece by piece if I consider it done.

Remark:
As I can not compress it down to a single commit via GUI it might be ugly from time to time as it will be quite a few commits. I suggest you close your eyes or give me a hint for a better working method ;-)

For everything which is on master feel free to further improve or correct the mistakes I might have done during migration.

I will especially take care for:

• Making the FAQ more general (not explicitly refering to geocaching.com only) whereever possible
• Updating the step-by-steps where our menu structure changed meanwhile
• Removing outdated FAQs

[Lineflyer]

@SammysHP
Any chance we get shorter permalinks to the seperate titles?
Functionality is OK, but they might get quite long if always the whole title is included. It might be enough to e.g. take the first 8-10 letters or a hash value calculated from the title if technically possible.

[Bananeweizen]

it will be quite a few commits.

I think that is perfectly fine. Cause it means that afterwards everyone can already rework the existing files, even though not everything is transferred yet.

[SammysHP]

Newline:

foobar \\
asdf

Permalinks:
We're limited to the functions that are provided by the liquid engine: https://github.com/Shopify/liquid/wiki/Liquid-for-Designers#standard-filters
(GitHub pages do not allow the use of additional plugins AFAIK.)

Instead of:

{{ item.title | escape | remove: ' ' }}">{{ item.title }}

we could use:

{{ item.title | escape | remove: ' ' | truncate: 10, '' }}">{{ item.title }}

[Lineflyer]

I continued on the work today and meanwhile got aware of the pitfalls regarding the syntax.
I will continue work maybe tonight, but after that I will not be online for a week due to vacation.

I would like to continue the migration myself, but feel free to improve the part which is already pushed to master now.
But I suggest not to modify the section structure or the sequence of the entires yet, as this will make the migration more difficult. We can start that as soon as the migration is complete.

[Lineflyer]

I am done with transfering it to the markdown file.
In the same step I tried to update and improve the entries whereever I recognized it to be outdated,etc.

I am sure there are still some format problems, typos and also the grammar might not be 100%.
Feel free to further improve or also propose new sections,etc.