ntno / mkdocs-terminal Goto Github PK

base on max content length?

https://www.nngroup.com/articles/change-the-color-of-visited-links/
could be an opt-in feature

consider:

• contrast to background
• contrast to unvisited links
• contrast to plain text
• contrast during link hover

ensure works for alternate palettes

need at least the version that has namespace feature

sometimes shows #, ##, and ### in toc
other times just # and ##

is it just depth that matters? not the actual number of hashes?

see https://webaim.org/blog/alt-text-and-linked-images/
comment from article:

Title is intended to provide supplementary information. If title is necessary for accessibility, then it is therefor NOT supplementary.

and

see https://usability.yale.edu/web-accessibility/articles/images

Image links should describe the purpose of the link, and must never describe the image.

and

https://usability.yale.edu/web-accessibility/articles/links

Image Links
In general, content editors should avoid using images as links. If an image functions as a link, the image must have alt text that conveys the location and purpose of the link. The alt text should not describe the image. Treat image links as links, not as images.

also:

• https://www.w3.org/TR/WCAG20-TECHS/G196
• consider what should happen if a title is provided for both the link and the image

we should add a built-in high contrast color palette
the colors should meet WCAG guidelines

• https://webaim.org/resources/contrastchecker/
• https://accessibleweb.com/color-contrast-checker/

tasks:

• test color palette
• add example page to docs
• add link to palette page

add section to
./documentation/docs/configuration/extensions/py-mdown-extensions.md

add to supported list in main index
./documentation/docs/configuration/extensions/index.md

example usage:
https://github.com/ntno/mkdocs-terminal/blob/main/documentation/mkdocs.yml#L45-L62
https://github.com/ntno/mkdocs-terminal/blob/main/documentation/docs/tile-grid/index.md?plain=1#L95-L99

leverage Terminal.css alert class?

check existing palettes to see which conform to WCAG contrast guidelines

• https://webaim.org/resources/contrastchecker/
• https://accessibleweb.com/color-contrast-checker/

tasks:

• report results
• make a decision on remediation (what will be changed if anything; document reasoning behind decision)
• create issues to track remediation work if necessary

see #108 for details on reasoning

https://terminalcss.xyz/ has nested list examples but currently they don't render correctly from markdown

yale accessibility guidelines say to avoid opening links in new window/tab
https://yale.app.box.com/s/ochc2c7zzhsj4wuk6fv41hbk5w8vhxt5

is this the general consensus? if so should update docs

is this possible?
do we need to create a dist and install that using pip?
is it worth it given that the watch functionality won't really be watching the theme files under development?
needs further investigation

invert terminal_prompt feature flag

see https://www.terminalvue.dev/story/src-card-story-vue?variantId=src-card-story-vue-0
and https://github.com/jfitzsimmons2/terminal-vue/blob/main/components/card/card.vue

see also:

• https://www.codeinsideout.com/blog/site-setup/markdown-syntax/#code-blocks
• https://squidfunk.github.io/mkdocs-material/reference/code-blocks/

see https://github.com/ntno/mkdocs-demo for example
new s3 bucket for each PR, deploy doc site to temporary website, teardown bucket when PR is closed

when an ordered list is added to a markdown page, any footnotes start counting at the next number following the end of the ordered list

Reproduction

when a unordered list is included, footnotes start at the number 1:

when a ordered list is included, footnotes start where the ordered list left off:

with ordered list:

1. First item
1. Second item
1. Third item
    1. Indented item
    1. Indented item
1. Fourth item 

Environment

• Version of this theme used: 3.7.0
• Version of MkDocs used 1.4.2
• Other relevant versions (pip packages, OS, browser): firefox, see attached pip-install.txt

points back to https://ntno.github.io/

reran 1.0.1 release job and it passed... seems incorrect

overview page for configuration section doesn't accurately describe section
currently the page focuses on just a subsection of the hideable component features
https://github.com/ntno/mkdocs-terminal/blob/484da138de9bb04f51b418790523648639744b2b/documentation/docs/configuration/index.md

• move hideable component intro
• add topics covered in configuration section with short summaries

• try out ' SiteImprove' accessibility checker for Chrome
• https://wave.webaim.org/

Describe the problem you'd like to have solved

I would like to be able to enter markdown for a tile caption and have it be rendered in the final tile grid

Describe the ideal solution

if the tile.caption is markdown then it should render correctly when md_in_html extension is enabled

ex:
tile.caption: Figure 8, *Misc. Project Notes*, pages 82, 83.
then 'Misc. Project Notes' should be in italics

Alternatives and current work-arounds

current workaround is to use html tags
ex:
tile.caption: Figure 8, <i>Misc. Project Notes</i>, pages 82, 83.

Additional context

https://ntno.github.io/mkdocs-terminal/navigation/section-indexes/
pictures first, just like with the other overview pages (tile grid, configuration, search, revision, etc.)

we should add translation support so that the theme can be used for sites in languages other than english
https://www.mkdocs.org/dev-guide/translations/

currently we load from MkDocs Page metadata
would be nice to be able to load from outside source file / api

Describe the problem you'd like to have solved

• remove temporary debug feature
  • documentation/local.yml
  • macros/debug.j2
  • partials/debug.html
  • base.html
• update pyproject.toml classifier
• #73
• investigate:
  • #11
  • #57

Describe the problem you'd like to have solved

i should be able to provide a markdown file name as the tile link_href

Describe the ideal solution

run link_href value through mkdocs url filter?

Alternatives and current work-arounds

have been providing a relative "directory" link. ie ./gruvbox-dark/ instead of ./gruvbox-dark.md

• see Gioni06/terminal.css#9
• see Gioni06/terminal.css#34

dark section title is confusing --- too similar to when a page is active (dark italics)

Describe the problem you'd like to have solved

The theme supports mkdocs-git-revision-date-plugin however there are no instructions on how to set it up

Describe the ideal solution

add plugins/ folder with index and git revision page
(similar to extensions/ docs)

Additional context

• add info about needing to add requirement
• add info about updating mkdocs.yml
• add pytests to confirm hide_git_revision_date functionality

todo stub

• see ntno/ntno.net/custom_theme
• add instructions about needing to install meta markdown extension

not sure we should say 'supported plugins'.... we don't necessarily want to promise to always and forever work with the listed plugins.
not necessarily willing to fix any issue that crops up related to plugin.
change to 'tested'? something to just indicate that it was reviewed and will probably work

there is probably a template for this

Description

when pytests run on windows-latest github action runner i get the following error:

self = <tidylib.tidy.Tidy object at 0x00000200870C3070>
lib_names = ['libtidy', 'libtidy.so', 'libtidy-0.99.so.0', 'cygtidy-0-99-0', 'tidylib', 'libtidy.dylib', ...]

    def __init__(self, lib_names=None):
        self._tidy = None
        if lib_names is None:
            lib_names = ctypes.util.find_library('tidy') or LIB_NAMES
        if isinstance(lib_names, str):
            lib_names = [lib_names]
        for name in lib_names:
            try:
                self._tidy = load_library(name)
                break
            except OSError:
                continue
        if self._tidy is None:
>           raise OSError(
                "Could not load libtidy using any of these names: "
                + ",".join(lib_names))
E           OSError: Could not load libtidy using any of these names: libtidy,libtidy.so,libtidy-0.99.so.0,cygtidy-0-99-0,tidylib,libtidy.dylib,tidy

.tox\py\lib\site-packages\tidylib\tidy.py:97: OSError

(see attached for full log)

Reproduction

install tidy with soop:

      - if: ${{ matrix.platform == 'windows-latest' }}
        name: Install scoop (Windows)
        uses: MinoruSekine/setup-scoop@main
        with: 
          scoop_update: false
      - if: ${{ matrix.platform == 'windows-latest' }}
        name: Install test requirements (windows)
        run: |
          scoop install tidy

then run pytest from tox.ini:

commands = 
    pytest {tty:--color=yes} tests {posargs}

References

#58
countergram/pytidylib#33

Environment

• windows-latest github action runner
• pytidylib-0.3.2.tar.gz (via pip)
• tidy-5.8.0-win64.zip (via scoop)

from scoop install:

Installing 'tidy' (5.8.0) [64bit] from main bucket
Downloading https://github.com/htacg/tidy-html5/releases/download/5.8.0/tidy-5.8.0-win64.zip (1.3 MB)...
Checking hash of tidy-5.8.0-win64.zip ... ok.
Extracting tidy-5.8.0-win64.zip ... done.
Linking ~\scoop\apps\tidy\current => ~\scoop\apps\tidy\5.8.0
Creating shim for 'tidy'.
'tidy' (5.8.0) was installed successfully!
HTML Tidy for Windows version 5.8.0

Describe the problem you'd like to have solved

pages can get quite long and it takes a lot of scrolling to get back up to the table of contents and the side nav.

Describe the ideal solution

there should be an option to add a "go to top" button which would move the screen to the table of contents and/or top of the page

just get '404 Not Found' without terminal theme

search results should update as more text is entered in search bar

• https://github.com/bartdegoede/blog/blob/master/assets/js/search/search.js
• https://www.mkdocs.org/user-guide/configuration/
• https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/
• https://www.mkdocs.org/dev-guide/themes/#search_index_only
• https://www.mkdocs.org/user-guide/configuration/#options

<meta name="robots" content="noindex">

what is this for / what does it do
do we need it in the theme? should it be optional?

we need automated testing for the theme

example use cases:
unit scenario
when tile.j2 macro is used to create a UI component but the required tile attributes are not included, no UI component is rendered

integration scenario
when palette: dark is set in mkdocs.yml, then dark.css should be loaded

i don't have a lot of experience doing automated testing for frontend projects so any help here would be extremely appreciated. even just a pointer in the direction of a simple example project would be helpful.

update: 1/17/23

• unit automation suites are set up

current todos:

• test section.indexes feature
• test side navigation menu
• test top navigation menu

update: 1/21/23

• mocking
• initial top nav tests

move developer notes elsewhere

would appreciate a second set of eyes since i copied most of this from mkdocs and mkdocs-material