Repository navigation
Make the website a delight to use - #70
Merged
Merged
Conversation
Every header gets a Search button and a sheet, and the search box becomes a real combobox that loads its index on demand and ranks results by page, with synonyms and "did you mean". The contents, the page list and the header now mark where the reader is, and phones get a bar naming the current section. Touch targets reach 40px, status changes are announced, heading anchors copy their link, and the theme toggle reports its state.
The docs take a wider frame with a reading measure on the text, commands wrap only between words with a hanging indent, chips of code never split inside a word, and wide tables become cards on a phone. Every page gets its contents at every width, heading links outside the heading, option rows that other pages link to, and code blocks that say whether they are a terminal, a file or a command's output. The changelog reads as versions, the search index holds the whole docs with the options, stories and front page, and 404.html is generated and sends a mistyped address to its page.
The report asked mathjax.rstudio.com for MathJax on every open, though it has no maths, so mathjax is now off. It also gets lang="en", alt text on every plot, an inlined favicon and a darker active contents item (5.3:1). The example report is rendered again from the demo inputs in the AMAP image, and check_site.py fails if it, or the Rmd, loads anything from another host.
…s are searchable A page that loads figures.js must carry one of the hooks figures.js mounts, or a script of its own that draws with it. The search index must have the shape the search box reads, with an entry for every option of the parameters page that lands on its row.
Generated pages no longer load search-index.js up front; site.js fetches it on first use, which is the global search's job. This commit goes in after that loader, so search keeps working on every page.
The test step now skips eggNOG and says how long it took, install is one recipe, and every page gives one answer on --skip_functional_annotation: no final_report.html, while amap_report.html is still written. Cut genes come back in pieces, the tutorial prints what its commands print, the outputs tree lists every file a run writes, troubleshooting has a heading per error, and pinning, the Singularity cache and the eggNOG database size are what Nextflow and the servers report. check_site.py fails on the old skip and contig-end sentences, and when the install command differs between the front page, installation and the tutorial.
The citation page gives APA, BibTeX and CITATION.cff as tabs, each with Copy, the July release month and the Paterna affiliation, and a paper with a resolved DOI for every tool that has one. The correction algorithm lists its steps in order and turns its long rules into a sentence and a list, and the custom reference's first step becomes a list with the details in a callout. check_site.py checks the citation page against CITATION.cff.
Each gene track, network and the metro map is now one tab stop whose genes are named and move with the arrow keys, hidden layers leave the pointer and the tab order, and the tooltip becomes a line under the drawing on touch screens and narrow figures. The ribbons and marked stretches reach 3:1 in both themes and differ by shape as well as hue, legends are built from what each drawing uses, and forced colours keep the palette. The hero plays when first seen, can be paused or stepped by phase, and the metro map fades the stretch a run without eggNOG leaves out.
Back and Next now sit right under the drawing, the text keeps the height of the story's longest step, and a picked or linked story scrolls into view; the chips and steps are in the page, so it no longer shifts as it loads. Each step sets the phase the drawing needs, so dropped calls fade at step 4, a copy takes its _2 name at step 6 and cut ends are marked at step 5, and steps that change nothing show hollow. Case 3 gets its story, Play waits as long as a step takes to read, steps can be linked as #key/4, and check_site holds the chips to how.js's stories.
The second piece of Rv1239c holds the protein's last residues, so its alignment is short of the start, not the end, and now fades on that side. Its tooltip says so, and the legend chip reads as short of the whole protein, which covers both.
benchmark.py scores Bakta's own calls by the same rules as AMAP's table, and the expected results gain two Bakta-alone columns. The front page's benchmark becomes a real ARIA table whose bars shade the part Bakta finds on its own, and check_site compares those numbers and lengths with the README.
With a mouse a tip floats above the gene unless the drawing is under 420 px, so the front page cards keep their size; touch screens and narrow drawings get the line under the drawing, which holds the height of its longest tip so pointing never moves the page. A protein of the duplication networks shows its ring only when the keyboard is on it.
The front page no longer loads the 1.9 MB report: its frame shows a 37 kB picture of the first screen, taken by tools/pictures.mjs, and loads the report on click. The open report is inert again when the pointer, focus or a touch leaves it, on Escape or on Done, and check_site keeps the picture under 80 kB.
Step 1 checks that Docker runs and how much memory it gives, step 2 is the test without eggNOG with the end of a real run under it, and a new step 4 says what to open. The builder writes the check and the run from one set of choices, with true notes for laptops, clusters and other species, radio groups for its questions and tokens that wrap between words; the quickstart's copy follows it.
The hero gives each sentence its line, a shorter lead, the CDC1551 numbers of the tutorial's run and an In and Out spec, and puts the drawing in a phone's first screen. Kickers show as designed, running text ends at one measure, the case counts print what their command prints with the meanings beside them, file cards name lineage folders and say which runs write them, and the FAQ says how long a run takes.
The summary's path was one unbreakable token wider than a phone's terminal. It now breaks after a folder, with the hanging indent of the line it continues, and the output under it is unchanged.
At 11 px the process names of Duplications and All genomes ran into each other. All genomes now sits 10 units to the right, clear of its neighbour and of the pangenome line.
Between 421 and 424 px the new search button pushed the header past the edge, and with WCAG text spacing it overflowed in several bands where main fitted; the compact header now starts at 439 px and site.js sheds the same items in order whenever the row still runs over. The results list no longer takes a Tab stop of its own, so Tab leaves the search at once. Docs pages fold the page list on phones again unless the page already folds it before the first paint.
On a phone, a heading whose last line reaches the right edge pushed the note past it, and the page widened to 426 px while the note showed. The note now moves above the line, against the edge, whenever it would not fit beside it.
The tutorial gave the test run's work/ as 98 MB next to 248 MB for its own runs. Measured the same way, du -sh, the test's folder is 97 MB.
A code block's background squared off its rounded corners, the quickstart's command builder stopped wrapping on phones and ran under its Copy button, and a 43-character file name kept whole as a table row's name widened the containers page past a 360 px screen. Code blocks keep their corners, the builder's command wraps as it does on the front page, and a row name longer than a phone's line breaks after a _ or a dot. The Output head of a command's printout also reads at 5.4:1 in the light theme.
The shorter bottom padding suits the generated pages, which end in the hairline row with the lab, licence and version. The front page and how-it-works.html do not have that row yet, so they keep the 56 px they had.
Play and Next now hold both of their words and show one, so the longer word sets their size: at the last step 'Start again' no longer pushes Back and Play aside on a desktop or wraps to two lines and drops the text on a phone. The light theme's legend chips for marked stretches take the same darker edge as the marks.
The sample sheet's tab stops are six columns apart, so every row's tab ends at the same column with room for the tab mark, and its rows run under the title row's Copy so they still fit a phone. The Singularity note no longer gives the converted image a size, the check's warnings are said not to stop it rather than never to, step 4 names amap-test/ for the test, and the outputs say that --skip_typing leaves the lineage out of the folder names.
At 390 px the wider Pause pushed the caption beside it onto a third line, so the front page card grew by 21 px when the drawing started and shrank when it ended. The button now holds both words and shows one.
At 1000 and 320 px the words of the second phase wrap onto a second line, so the card grew by 24 px while that phase played. The line now measures all four phases at its width and keeps the tallest.
Below 600 px the story chips sit in rows that scroll sideways, and the scroller cut off the top of a focused chip's outline. The rows now keep 5 px inside them above and below, with the same height as before.
The HPC figure names singularity.cacheDir as the pages do, the overview's Case 3 card steps through its own story, README installs Nextflow with the site's one recipe and the install check covers it, and long hashes and sheet paths no longer run off a phone. The search index goes out packed and is checked against its 230 kB budget, .visually-hidden is defined once, and the changelog gains the website, report and benchmark entries.
The README's drawings, the shared-link card and the example report's poster and section pictures now show the merged drawings and the offline report. tools/pictures.mjs could not draw the README's playing hero, whose folder was only defined inside the other README part, and now holds each step as long as the front page does.
Search now handles questions asked in plain words, Troubleshooting explains a sample set aside after its retries, and the pages say what the pipeline does when a check fails, on a laptop, with eggNOG and on a cluster queue. Commands keep their backslashes and indents together on phones, selected states survive forced colours, focus and tooltips stay in reach, and links to renamed headings and the changelog's GitHub anchors still land.
Every size now comes from a 17px x 1.125^n scale, spacing from a 4px grid, and corners, surfaces, inks and shadows from a few named steps per theme. Drawings stand on plates whose colour their halos and controls follow. The light theme gets a logo of its own, drawn from the logo by tools/logo_light.py.
The hero's drawing spans the column as Figure 1, its counts read out beside it, followed by the genome-wide numbers coloured by what they count. Chapters hang their numbers in a margin column, the five cases become one lettered figure and the benchmark and docs tables are set as a paper sets them. Docs pages get numbered groups, a standfirst and captions with a bold lead-in.
Dotted leaders join a drawing's row names to their rows, fading with the rows still to come. Below 1100px the hero's counts move under the drawing and its GitHub button gives way, so every gene stays named and the way in stays on one line. The how-it-works crumbs take the docs' caps label.
tools/pictures.mjs draws them from the site, so the README's hero, metro map and outcomes, the social card and the touch icon now show Figure 1 with its readout column and the plates' new surfaces.
A chapter head with no lead, as the questions' is, sits 24px over its list instead of 48, so the list does not float under the margin's number.
The overview's case 2 and 3 tags sat at 4.4:1 on their tint over the page; #0c724d holds 4.5 and more on every light surface. The light README pictures are redrawn with it.
The Previous and Next cards stack on a phone and table heads wrap again, so no page scrolls sideways from 320 px up, and the sample sheet figure no longer inherits the front page's two columns. Drawings keep their words at 10 px or more on a phone, the metro map's labels and the duplication networks' names keep off the lines, and the benchmark puts its counts over slim bars where Bakta's line would cut them. The report cover, the stage card's bar, the header under 360 px, the footers, the browser bar colour and the species names now match the rest of the site.
Paururo
added
documentation
The grid of design C without its glows: minor lines every 16 px and major every 80 on one fixed layer, painted once and lined up with the column's edge at every width, a ruler of ticks under the header, and the plates' corners drawn in the accent. The docs keep only the major lines, quieter in the light theme, and no text on the page ground drops below AA, even where two lines cross.
…in a rail A docs page's sections now sit under its entry in the sidebar, the one being read marked as you scroll, its subsections unfolding and the list scrolling itself to keep it in view; the right-hand column is gone, the docs share the front page's frame, and phones keep the folded box. From 1440 px the front page carries Figure 1 and its seven chapters in the margin, numbered as the page numbers them, and check_site holds the two to the same order; narrower, the search lists them and a phone's bar names the one in view.
The sidebar list is cut short at the foot of a page and the current page stays pinned over its contents, which no longer fold as you read; the rail follows the reader's text size and names chapters by their kickers on phones. The graticule is now the page's own background, calmer under the front page's reading chapters in the light theme, on the docs column's edge between 861 and 1215px, and gone from print and forced colours. check_rail finds chapters as the stylesheet counts them and checks each rail name against its chapter.
Paragraphs and card texts no longer end on one word and labels balance; tracking and line height come from tokens, numbers stay with their units, cells share a baseline, and the light theme gets its own brand teals and a gradient that reaches its last stop. The front page's column, the docs' sidebar and the stepper are whole squares of the graticule, plates share one inset, step 3 splits where its builder does, Figure 2's panels draw their tracks on one line, and a jumped-to chapter lands with its rule level with the sidebar's search.
Hover styles live only where there is a pointer, every control fades at one speed from motion tokens, cards that are links answer with an accent edge instead of a lift, and press, disabled and checked states are drawn alike; selecting text skips the labels of buttons. The 40px touch rule now comes after the controls it enlarges and reaches tabs, segments, chips, footer links and anchors, head-less code blocks keep Copy in a strip above the text on a phone, and the header's links and buttons share one height and spacing.
The 404 drawing is a plate with corner marks, draws a narrower version on a phone so it shows whole, keeps its search results inside its box and pins the footer to the foot of a tall screen. A light browser tab gets a favicon recoloured by tools/logo_light.py, and the header's icons carry their own size so a page whose stylesheet fails to load does not draw them a screen wide.
Mark frames keep displaced gene names off them and a first-row callout may start in the names' column, so Figure 12 and the overview's callout stay clear, and the missing card names the gene it puts back. Count labels hide where their bar cannot hold them, gauge ticks sit on their values and drop the crowded ones on a narrow gauge, a two-panel story says "Tap a gene" once and the light report band shows. Printing gives the light palette, the headline and every drawing at its end without the screen's controls, and without JavaScript the dead controls go and each drawing says why it is missing.
The page no longer scrolls behind the open search sheet, and Ctrl+K pressed again keeps the element Esc returns to. A search with no match offers All the docs, the key hint names only keys that do something, flags stay whole in the results, and words like "the" give a hint instead of every page.
Copy keeps its width when it says Copied, restarts its timer on every click, and on a refusal selects the text and says which keys to press. Tabs take Home and End, the builder explains a parked Keep the eggNOG database, and a touch phone neither offers the / switch nor opens a story on a screenful of space.
A theme switch no longer leaves buttons and cards fading from the old colours, and a light page colours the browser bar from its first frame. The missing page labels its search box, and opened by its own address it no longer fills the box with 404.
A number no longer ends a line apart from its unit, an initial apart from its species, a case or step apart from its number, nor one end of a range from the other: the docs, the hand-written pages, the metro's notes and the story steps all bind them the same way. Species in captions, gauge labels and the changelog are italic, the citation and article-led headings hold together, and file names in the page contents break only at a slash.
The docs now agree with the front page and with each other: one name per case, report, profile kind and page link, one wording for the image size and Docker's memory setting, the measured test time, thousands separators in prose, and the Mycobacterium tuberculosis complex spelled out where MTBC first appears. Figures follow suit: the metro names the reports as the nav does and never a missing station, the results map lists amap_report.html, captions name pages that exist, and pointer hints stay off touch screens.
Every title ends in the same way, the missing page is Page not found, and each docs page's description says what AMAP is; the front page spells out the Assisted Microbial Annotator Pipeline. Search snippets read as sentences, from a table's rows to a story's steps, the changelog's first section is On main, and the changelog drops its read time and title-case headings.
Number the duplication figures in order, keep option names, file names and K-12 whole on a line, and let one-line blocks, the BibTeX and the metro map fit instead of scroll. Tables sit on the grid, the parameters tables share one column, the report poster is sharp, and a keyboard focus says which arrow keys move on. Search lists each page once and without stray spaces, and Done, the hero's counts, the step list and the eggNOG switch now do what they show.
The sheet and the box under the title list only a page's main sections, so while a subsection was read nothing in them was marked and the bar that names it opened the search box and its keyboard instead. They now mark the section the subsection belongs to. Opening from the bar also clears a search left in the box, which hid the contents and left the sheet empty.
The box was held to 68 characters of its own smaller type, so on a tablet it stopped short of the box of pages above it, the headings and the tables. The reading measure is for running text, and this box is navigation like the one above it, so the two now share their edges.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Eight reviews of the live site (first visit, navigation, visual design, drawings, phones, accessibility, content, performance) found 128 issues. They were merged into one plan, built in five parts that touch separate files, merged here, and reviewed again with fresh eyes. A visual design pass followed, chosen from three prototyped directions by a panel.
What a reader gets
/or Ctrl/Cmd+K). The index covers the whole docs, every option (#opt-<flag>), the stories, the FAQ and the changelog.Checked
tools/build_docs.py --checkandtools/check_site.pypass. check_site gained rules for stories, figure scripts, the search index (packed, under 230 kB), the front page, anchors, install commands and citations.