Re: ruby-team.pages.debian.net | added my workflow-paper as CONTRIBUTING page (!1)

[Klaumi Klingsporn <klaumikli@gmx.de>]

Am / On Sat, 28 Nov 2020 03:05:50 +0100
schrieb / wrote Daniel Leidert <daniel.leidert@wgdd.de>:

> JFTR: The minima theme doesn't know sub-pages or
> collections by default. We'll have to create something
> ourselves. Probably a collection with a main page and
> then link to this page via _config.yml.

O.k., we want a configuration, where we can put my
beginners-manual and maybe others in the future into a
special directory, let's call it 'manual' and put only
general information in CONTRIBUTING.md, which links to
special manual(s) in the manual-directory. And we would
like to have an additional side-bar menu for the manual(s),
because it makes navigating through them much easier ;-)

I had a quick look into jekyll and as far I understand
this thingy this would need:

1.
To create the directory 'manual' of course

2.
to add a new scope in config.yml, like this:

  - scope:
      path: "manual/*"
      type: pages
    values:
      layout: manual

3.
to create a directory '_layouts' and create a 'manual.html'
file (as supplement to the themes layouts) which looks like:

---
layout: manual
---
<header class="page-header">
    <h1 class="page-title">{{ page.title | escape }}</h1>
 </header>

<div class=sidebar>
<ul>
    {% for item in site.data.samplelist[page.sidebar] %}
      <li><a href="{{ item.url }}">{{ item.title }}</a></li>
    {% endfor %}
</ul>
</div>

<div class=manual-content>
   {{ content }}
</div>

so that for every page, which has the page front matter
'sidebar: toc' set, there will be created the sidebar-menu
typ 'toc' with the css-class 'sidebar' and the content will
follow the styles of the class 'manual-content' (We need
these new classes to put the two boxes beside each other.)

3.
Then we have to define this sidebar-menu typ 'toc'.

Jekyll doesn't seem to have the possibility to auto-generate
a menu with submenus out of a given directory-structure
with source-files (wouldn't that be the goal of a
website-generator?), so we also have to create a
sidebar.yaml file in the _date folder which would look like:

toc:
  - title: Manual 1
    subfolderitems:
      - page: <PageMenuEntry 1>
        url: /manual/<subdirctory-name>/<page-name>1.html
      - page: PageMenuEntry 2
        url: /manual//<subdirctory-name>/<page-name>2.html
      - page: PageMenuEntry 3
        url: /manual/<subdirctory-name>/<page-name>3.html
  - title: Manual 2
    subfolderitems:
      - page: <PageMenuEntry 1>
        url: /Manual/<subdirctory-name>/<page-name>1.html
	... <and so on>

and we would have to change this file with every new
incoming manual (what a mess!)

4.
We have to create a new _sass/minima directory and copy the
file costum-styles.css from the minima theme there, so that
it would overwrite the themes one when processing the page
by jekyll, and add there the styles for our new classes
'sidebar' and 'manual-content', especial the values for the
position and sizes of both boxes themselves
as well as for 'ul' and 'li' inside of 'sidebar'.


So all in all, it's a lot to change and I'm no jekyll-freak
at all. I actually find it unbelievable that there should be
no possibility of auto-generating the menu out of a
directory/files-structure in the manual-directory. I'm
certainly missing something.

Sorry, but this changes should be done by someone else who
knows jekyll better than me!  (I'll stay with my
webgen.) After the changes are done, I'll be glad to split
my guide and push the parts into the appropriate place(s) of
the changed site.

Klaumi


-----
Klaumi Klingsporn
mail: klaumikli@gmx.de
web: www.klaumikli.de