The mischback.de from mischback

Provide (custom) icons

Icons should be applied as eye candy to content boxes, navigation, etc.

To maintain scalability, the icons should be provided as SVGs. They may be created using Inkscape, but will require (manual) optimization.

Create Icons
- Meta (articles, aside box)
- Quote (articles, aside box (tubhrq))
- Also in this series (articles, aside box)
  - some sort of bookshelf or something reminding a library
- Tags (articles, aside box; main body of tags documents)
- Development (main body of documents in this category)
- Miscellaneous (main body of documents in this category)
- Keyboard (main body of documents in this category; higher priority than misc) Not required without dynamic icons
- /now (top navigation)
provide the means to include and style these icons
- Preferred Approach
  - ~~Async loading of a dedicated icon file (icons.svg) containing the icons as SVG symbols and inlining them using JavaScript~~ not required, as use can be applied to an external resource from the DOM; NOT POSSIBLE from within the CSS!
  - ~~Using JS (Progressive Enhancement) to inject the icons into the DOM (SVG use)~~ NOT REQUIRED, see below
  - Just insert the icons at the required positions, using SVG use in combination with Sphinx's pathto() function
    - ~~still requires some logic, but the "dynamic" icons are known at build time, so the icon can be finally determined.~~ Skip dynamic icons for now.
    - set appropriate ARIA roles, so that the elements are marked as purely visual styling and are not considered for screen readers
    - don't have to meet the contrast requirements!
  - have the actual styling already included in the overall style.css

CSS Validation

html5validator can also be used to check CSS files
does this work for minimized files?

Blog-style tags for ``Sphinx``

The content will be ordered using big categories, like Development, Knives, Misc. For additional ordering / more specific sorting, blog-style tags may be used.

There is a corresponding question on SO; the highest rated answer mentions Sphinx's built-in index directive.

Sphinx's documentation has a guide on developing a recipe extension which also incorporates a custom index. This may be a really great resource, if the built-in index is not sufficient out of the box.

Internal Analysis Robot

Idea

Have the (generated) website placed in a container (e.g. Docker) and let it be analyzed by a robot / spider.

Check every document and track the following information:

internal links incoming (must be derived from analyzing other documents!)
internal links outgoing (tracked by document, including counts, disregarding #targets)
external links outgoing (tracked by URI, including counts, disregarding #targets)

Implementation in Python, most-likely multithreaded with a configurable number of worker threads beside the main management thread.

Create build pipeline for Stylesheets

Notes

sources: scss
target: css

Implementation

libsass-python (the actual compilation)
stylelint, run through pre-commit (linting)
- https://github.com/stylelint/stylelint
- https://github.com/thibaudcolas/pre-commit-stylelint

Create a coherent visual style

While this is highly related to #28, it's more about the general look'n'feel, e.g. how borders and shadows are applied.

Make ``content_tags`` a standalone extension

Original Implementation #14 / #18

Additional Issues

Just collecting this here, will be converted into actual issues when moving to dedicated repository.

provide required templates from within the extension
- might require manipulation of Sphinx's template search path
ensure compatibility with existing themes
display tags in sidebar (??)
move KeyError handling to CTTag.rm_doc() (L291)

Create the Colorscheme

Readability is the primary factor
- high contrast values (foreground/background; minimum is AA)
- generally greyscale with popping contrast colors
- outstanding color for hyperlinks in the text body
use rgb() / rgba() instead of #rrggbb

Deployment

Things to consider for the deployment (might be relevant for the webserver configuration)

Use .build/404/index.html as custom 404 handler
map /favicon.ico to the actual location in _static/icons/

``/now`` page

See https://www.errbufferoverfl.me/now/ and more specifically https://nownownow.com/about

Webfont Improvements

This is a follow up to #30.

Pareto 20%

match the webfonts as good as possible with system fonts
- Flash of Invisible Text (FOIT):
  - font-display: swap;
- https://www.cssfontstack.com/
- https://web.dev/css-size-adjust/
- https://www.zachleat.com/web/comprehensive-webfonts/
- https://meowni.ca/font-style-matcher/
  - MonaSans:
    - fallback font: Verdana (availability Win/Mac > 99%)
    - MonaSans settings
      font-family: "Mona-Sans.woff2" font-size: 18px line-height: 1.5 font-weight: 400;
    - Verdana settings
      font-size: 16px line-height: 1.7 font-family: Verdana

Related / Follow up

#34 for further technical optimization.

How to activate Jinja2's debug extension from Sphinx

Turn #5 into an article.

Update ``tox``

tox 4.0 was released and is not backwards compatible.

However, updating tox introduces errors in CI, see https://github.com/Mischback/mischback.de/actions/runs/3726415701/jobs/6319849632

Eventually this has to be done, but will require a little more effort.

How to make the template configurable from reST source file with ``Sphinx``

See 44ac2d5

Build the custom theme

Choose a SSG

Choose a Static Site Generator

Prerequisites

use a Static Site Generator
prefer Python-based SSGs but don't rule out anything
Content may be split into categories, e.g.
- development for everything related to IT: programming, administration, projects, ...
- there may be more categories, but as of now it is questionable, if they should be a dedicated category
- miscellaneous for everything that does not fit clearly into one of the other categories

Assumptions

primarily text-based content
mostly in English without need for a l10n engine
certain pages in German (without need for a l10n engine)
a minimal set of pages in English and German (probably candidates for a l10n engine, but may aswell be provided as dedicated documents)
this is not a blog, so content doesn't need to be sorted / sortable by date
webserver is available (Nginx, full HTTPS-compliant)

Functional Requirements

Backlog

This is issue is meant to collect everything that is not handled immediately.

Inline Code Highlighting: Is this required somewhere?!
tag_index.html should provide the available tags as a tag cloud
- Ref: https://dev.to/alvaromontoro/create-a-tag-cloud-with-html-and-css-1e90
(Breadcrumbs) add some nerdyness, e.g. using a ::before element to insert $ pwd

Update ``pre-commit`` configuration

update included repos (there is a command for this!)
Evaluate mailsrv config, has some more Python-related stuff
Run Node/JS-based tools from the local NodeJS-installation instead of pre-commit hooks

DSGVO-compatible server configuration

This will still need more research!

Ok, so the DSGVO / GDPR considers even the users' IP address personal data, which means, that storing and processing this data is regulated (strictly).

On the other hand, protecting my own server, e.g. fail2ban, works by analyzing the log files and requires the real IP addresses to work properly.

Resources

https://serverfault.com/questions/980831/configuring-nginx-for-gdpr-rgpd-dsgvo-compliance-using-anonymized-ips-on-ol
https://www.supertechcrew.com/anonymizing-logs-nginx-apache/ Contains full logs for errors, anonymized logs for regular access

Functional Requirements

Dependencies

#120

Create the Readme

give executive summary
lots of badges
licensing
- source: MIT
- content: tbd, some CC with attribution?

Update SCSS pipeline

As of now, the project uses python-libsass, but libsass is considered deprecated and will not longer receive updates.

Actually I encountered a bug during theme development: while using rgba(0, 0, 0, 0.95), python-libsass generates "black", which is - obviously - wrong. A manual test with dart-sass is successful.

Implementation Idea

use sass through NodeJS (NPM package)
~~incorporate more NodeJS packages:~~
- ~~postcss~~ moved to #54
- ~~purgecss~~ moved to #54

Move project-specific extensions into a dedicated directory / package

Currently, Sphinx's configuration file conf.py acts like one of the project's extensions.

While this works reasonably well for small use-cases (see #5), it is not the desired result.

To Do:

Sphinx's most basic tutorial places the (custom) extension in a folder _ext in the source directory.

From my understanding, the _ext directory may be placed anywhere. It has to be added to Python's PATH. See the section on extending sys.path.

Namespacing might be an issue, so make sure that the project's dedicated extensions don't conflict with other existing extensions (or other packages).

Steps

create [REPO_ROOT]/extensions/mischback

add [REPO_ROOT]/extensions to Python path

in conf.py:

import sys

# add the project-specific extensions directory to Python's path
sys.path.append(join(REPO_ROOT, "extensions"))

create [REPO_ROOT]/extensions/mischback/sphinx_jinja2_debug.py:

def activate_jinja2_debug_ext(app):
    """Activate Jinja2 debug extension.

    This function is intended to be connected to ``Sphinx``'s
    ``builder-inited`` event (see
    https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx-core-events)
    and will then navigate from the app to the ``jinja.Environment`` and call
    its ``add_extension()`` method.
    """
    if hasattr(app.builder, "templates"):
        app.builder.templates.environment.add_extension("jinja2.ext.debug")

def setup(app):
    """Register the extension with Sphinx.

    This function is required by ``Sphinx``'s extension interface, see
    https://www.sphinx-doc.org/en/master/development/tutorials/helloworld.html#writing-the-extension
    for reference.

    It connects this plugins (only) function with the ``"builder-inited"`` event, see
    https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx-core-events
    for reference.
    """
    app.connect("builder-inited", activate_jinja2_debug_ext)

use the new extension

in conf.py:

extensions = [
    # ...
    "mischback.sphinx_jinja2_debug",
]

make the extensions setup() function return the (desired) dictionary (see dry-coding here)

Activate ``Jinja2``'s ``debug`` extension

Problem

For theme development it is not strictly required but would be nice to determine, what is placed in the rendering context.

Jinja2 >= 3.0.0 does provide the jinja2.ext.debug extension, which does provide a {% debug %} tag for this purpose.

However, that Jinja2 extension is not activated by Sphinx (which is good and expected).

Possible Solution A

The extension might be activated by calling add_extension("jinja2.ext.debug") on the Jinja Environment object (Reference).

Tracking this object down is not as simple as expected, but probably it can be achieved this way:

# in file conf.py

def activate_jinja2_debug_ext(app):
    """Activate Jinja2 debug extension.

    Prototype of this function is based on 
    https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx-core-events

    FIXME: If this works, make sure to add documentation, using the references
           from the research. Quite a ride through ``sphinx`` source code!
    """
    app.builder.templates.environment.add_extension("jinja2.ext.debug")

def setup(app):
    # Connect a custom handler to the ``builder-inited`` event.
    #
    # https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx-core-events
    app.connect("builder-inited", activate_jinja2_debug_ext)

# sphinx.application
# ``_init_builder()`` suggests, there is an attribute ``builder`` on the ``app`` object
# see ``create_builder()``, which calls ``sphinx.registry.create_builder()``;
# both of these functions return a ``Builder`` instance

# sphinx.builders (in ``create_template_bridge()``)
Builder.templates = BuiltinTemplateLoader() 

# sphinx.jinja2glue
BuiltinTemplateLoader.environment = SandboxedEnvironment()  # this is from jinja2.sandbox

Resources (``sphinx``)

Extensions / Plugins

Guides / Articles

Subsetting of fonts

Fonts are one of the crucial assets of the website.

They have direct impact on the layout / theme (obviously) and the overall usability of the website. Furthermore, search engines reward fast loading times, tiny to none layout shifts, ...

As of now, the project uses three different fonts:

Mona Sans (default font for text bodies, sans-serif, variable font)
Crimson Pro (serif, just used for quotes)
Hack (monospaced, for source code)

All of them do include a rather huge set of glyphs, most likely a lot of them will be completely unused. Subsetting removes glyphs from the font, making the required filesize smaller.

Follow up to #30, related to #55

Requirements

include subsetting into the build process
remove all un-used features of the fonts
determine un-used glyphs automatically
output format should be woff2
Licensing might be an issue
- SIL OFL v1.1 prohibits, that derivative works (and subsetting the font might count as that) are distributed under the same name

Font Selection

This issue tracks the initial implementation of fonts.

Pareto 80%

Related / Follow up

#55 for improvements of the webfont implementation
#34 for further technical optimization

[Experimental] Linters for prose

https://www.writethedocs.org/guide/tools/testing/#vale
https://github.com/errata-ai/vale
https://vale.sh/docs/topics/config
- https://github.com/jdillard/sphinx-sitemap has vale setup in its CI workflow

Spellchecking

https://github.com/hunspell/hunspell

HTML(5) Validation

See https://github.com/svenkreiss/html5validator

https://github.com/anishathalye/proof-html

Integrate images into build

While working on #31 one (unresolved) issue was, that the images are not actually part of the repository and thus, can not be considered/checked/processed during CI.

There are some possible solutions:

Integrate the images into the repository
While this is possible to track binary files with git, it's not desired, as it may lead to a bloated repository, as every updated version of an image would result in an additional blob, effectively doubling the size, making the repo grow
Use git-lfs
git-lfs stores only references to the binary files in the repository and stores the actual files elsewhere. This is kind of desired, but may require an external git-lfs server, because GitHub has quite strict rules about storage capacity and bandwidth. This external git-lfs server may need massive storage capacity, as it will hold all versions of any binary asset.
Going old school and keeping track of the images manually in an ignored folder.
This is the current approach. It only requires the images to be available locally. CI can not create a full build of the website!
Manual replication of git-lfs
Store only references (and possibly hashes) of the files within a JSON file in the repository. During CI, download the files from a (known) source, compare the file hashes and create a full build.

Articles tend to be quite long, so the primary navigation (in the page's header) is most likely not visible. On the other hand, the user might find that the article is not living up to their expectations, so they want to re-navigate while they are in the middle of the page, so the secondary navigation (in the page's footer) is not (yet) available, either.

Requirements

hide button until primary navigation is not visible
on mobile devices/single column layout only show the button, when the user swiped up. It is assumed that the button will cover parts of the content, which is not desired. But when the user scrolls up (just a tiny bit), it is assumed that they would like to return to the top, so support them with a button.
on desktop devices/two column layout the button may be placed in the area of the aside and can always be visible.
icon and text (for accessiblity reasons)
styling in the site's style.css
required JS is provided as Progressive Enhancement, meaning visitors without activated JS simply get no button, but there is no error either.

Resources

https://www.nngroup.com/articles/back-to-top/ Including design guidelines

Create a custom ``pygments`` style

I have built my personal vim colorscheme, which works pretty well as of now.

Wouldn't it be great to have this colorscheme available for source code listings on the website.

References

Requirements

specify file path to the related file
automatically add a link to that file in the aside box
use the target's title as title of the link

Beautify HTML build artifacts

Originally prettier was used to beautify HTML build artifacts. While implementing #7 in #20 this proved to raise several issues.

as of now, prettier is used to beautify the HTML after generating it from Sphinx/Jinja2
prettier is highly opinionated and is meant to not be configurable (see prettier/prettier#5246)
there are alternatives to prettier for the given task, current favourite would be html-tidy, which is available with Python bindings
KEEP prettier for formatting SCSS/TypeScript source code during pre-commit

As an alternative to prettier tidy-html5 might be used. It has Python bindings provided by uTidyLib.

Implementation Idea

use utidylib's bindings in a Sphinx extension, hooked to the build-finished event

Caveats

utidylib does not install the required tidy package / binary / library
How can this be done in a (semi automatical) way? I don't know why, but it just works in CI.

Custom Jinja template tags

Add a custom Sphinx extension to provide custom template tags / filters for Jinja2 templates.

Required Tags

date formatting
- take a datestring ("YYYY-mm-dd") and format it according to a format string
- basic internationalization?
- Reference: https://stackoverflow.com/questions/4830535/how-do-i-format-a-date-in-jinja2
- (the debugging extension also provides access to Jinja2's environment)

Privacy / Datenschutz
- Ref: https://dejure.org/gesetze/DSGVO
  - What: https://dejure.org/gesetze/DSGVO/12.html
  - Art. 13 defines, which information must be provided:
    - Name and means of contact (is a mail address sufficient?!)
    - Which information is stored/processed?
    - Why is that information stored/processed (most likely Art. 6 (1) f) "Berechtigtes Interesse"; requires explanation, what is that interest (providing, maintaining and improving the service)
Contact / Kontakt / Impressum
- Ref: https://dejure.org/gesetze/TMG
- Esp. §5 (1) / (2)

Resources (German)

Responsive Image Extension doesn't work for an image included in two different documents

Description

While working on the category overviews, an existing image was included for testing. However, on running Sphinx, only one instance of the image was picked up by the extension, the other got marked as No responsive image sources, creating non-responsive image for ....

Quick Research

The problem might be in ResponsiveImageCollector.collect_source(). The ref_path or the conversion into a Path object results in a non-existing path (below the document's own path).

To reproduce:

turn on Sphinx's verbose logging
check the extension's logging messages for Responsive image source not found: [PATH]

Stroke text

I want ~~stroke~~ text, which is no part of Sphinx by default!

Resources

https://github.com/sphinx-notes/strike
- this is - more or less - a ready-to-use extension
- Problem: it uses a <span> element (and the corresponding styling) intead of the (desired) (semantic) elements (<s> / <del>)

Responsive Images

Though I have already created a tool to generate the required image variants to make responsive images work (ImP), this might not be sufficient / desired for this project.

Requirements

Build pipeline

Create an actual build pipeline:

Stages

Dependencies

#120

Reference

colorizer, which was one of the sidetracks that significantly impacted building this website, has the additional benefit of having implemented a working cache busting in its v2 branch.
Related: #61

Create the overall structural layout

General

semantic markup
- ARIA roles where required
responsive layout, without JS, pure HTML/CSS

Layout

Templates

Article
Indexes
Tag Index
Tag (detail)

Linter for ``Jinja`` templates

https://github.com/Riverside-Healthcare/djlint
- Already used in Django projects
- Needs a configuration item in pyproject.toml (see documentation)
~~https://github.com/aristanetworks/j2lint~~
- opinionated
- needs evaluation: Focus are not really HTML templates, but rather Ansible templates. The general applicable rules are de facto included in djlint
https://github.com/thibaudcolas/curlylint
- needs evaluation

System Font Stacks

Font selection was a real issue while coming up with a design, and finally three major fonts were selected and are - as of now - provided as web fonts.

Everything is working fine, but...

fonts add around 250kb to the website's weight
they add build complexity (if/when further optimisation is applied, see #34)
external dependencies mean possible licensing issues (this should have been covered during selection already, but license terms might change and have to be watched; see #30)
Flash of invisible Text (FOIT) / Flash of unstyled Text (FOUT) will happen!

As an alternative, system font stacks may be used. The major drawback is loosing some control of the actual design, as the available fonts may deviate heavily between different users/devices.

mischback / mischback.de Goto Github PK

mischback.de's People

Contributors

Watchers

mischback.de's Issues

Idea

Notes

Implementation

Additional Issues

Pareto 20%

Related / Follow up

Choose a Static Site Generator

Prerequisites

Assumptions

Functional Requirements

Resources

Related

Meta

Functional Requirements

Dependencies

Implementation Idea

To Do:

Steps

Problem

Possible Solution A

Extensions / Plugins

Guides / Articles

Requirements

Pareto 80%

Related / Follow up

Spellchecking

Related

Requirements

Resources

References

Requirements

Implementation Idea

Caveats

Required Tags

Related

Resources (German)

Description

Quick Research

Related

Resources

Requirements

Stages

Dependencies

Reference

General

Layout

Templates

ToDo

Recommend Projects

Recommend Topics

Recommend Org