Tiny feel-good feature suggestions

[FlorianHeigl]

Hi,

some small things I had picked up. I had my documentation really, really finished[tm] and then handed it out to a few people to see how practical it was, reached out to get the style guide and started working that in. It's like 80 pages, so now I feel less bad that my docs are also more than just 5 pages ;-)

anyway, there's cover and back pages, right?

• The front cover (in book mode anyway) ought to be separate from the first chapter's ("pages") cover and just give the title/description of the site. But I think there's no notion of a "book" cover, only "chapter" covers. Right?
• Similar story applies for the last backside
• The chapter cover pages should never print on the back of another chapters last page. I mean they should be odd pages, and the back covers should be even pages.

The last one is really a problem, I ended up reprinting some cover pages individually and glueing paper on the backsides where it went wrong.

Those apply independent of how many pages a single markdown doc turns into. otherwise you always got trouble printing the whole "book"

I feel it would need to be solved via the page numbers and automatically leaving a blank page if needed, but I know it might also just be because I can't figure out a better way.

For the record I'm also lost between the different places with description, title, site name etc., but that is a general issue, I'll need to draw a map of where and what is set from what variable and injected in which space. (let's see if that happens :-)
Same goes with the fonts and such definitions, need to ensure what I do for html also happens for PDF. basically what I'm gonna do is create a completely separate documentation repo now that is just for styleguide regression testing. It feels weird, IDK if others do that and how far you go with templating. It feels overengineered to me have such a strong separation between style and content but it appears needed?

tl;'dr: currently there's different stylesheets for print (plain, pdf.scss) and web (the front/back cover jinja bits) and general (custom.css). what is the feasibility of re-use there?

[nbanyan]

It would be nice to have a clean way to have a book cover (front and back) that is separate from the section cover pages. For the front book cover you can use the following Jinja in the front cover template. A different condition would be needed if the first content page is not 'index.html'.

{%- set is_homepage = (page.url == 'index.html') -%}

{%- if is_homepage -%}
    {%- if 'exporter' in config.plugins -%}
        {%- if 'formats' in config.plugins.exporter.config -%}
            {%- if 'aggregator' in config.plugins.exporter.config.formats.pdf -%}
                {%- if 'covers' in config.plugins.exporter.config.formats.pdf.aggregator -%}
                    {%-  set covers = config.plugins.exporter.config.formats.pdf.aggregator.covers -%}
                    {%- if covers == 'limits' or covers == 'all' or covers == 'book' -%}
                    {%- set book_cover = True -%}
                {%- endif -%}
                {%- if covers == 'limits' -%}
                    {%- set section_cover = True -%}
                {%- endif -%}
            {%- endif -%}
        {%- endif -%}
    {%- endif -%}
{%- endif -%}

{%- if book_cover -%}
    <div class="exporter-cover-page">
        ...
    </div>
{%- endif -%}

{%- if section_cover -%}
    <div class="exporter-cover-page">
        ...
    </div>
{%- endif -%}

For the Stylesheets, I've found it useful to have three separate stylesheets:

• Normal CSS files for how it looks in the web browser
• Print from Browser (@media print) so things render well when using the browser's print dialog.
• Exporter SCSS for exporter to compile and apply to handle variances that are unique to its rendering.