61438453e9f8be7a5949725a688ac6cf709add28
lrnassar
  Tue Apr 28 13:06:10 2026 -0700
Restructure /docs/ landing page for new users; add docs-page styling. refs #36894

docs/index.md: rewrite as a beginner-first landing page. Replace the prior
five-section structure with a flat five-H2 outline -- Tutorials, Visualize
your own data, Share your work, Download data, Get help -- so every entry
in the sidebar TOC maps to specific content rather than to a vague
grouping. Promote the tutorial table from a buried H3 to top-level
content. Drop sections that don't serve new users (the "Understanding
assemblies/annotations" primer, the MySQL bullet, the mirror paragraph,
the Multi-Region View specific mention, and the four scattered "Relevant
FAQs" lists). Consolidate help into a single closer with contact, FAQ,
workshops, and the suggestion form. Distinguish custom tracks vs track
hubs ("simpler option" vs "more powerful and configurable"). Make
tutorial titles the table links and drop the redundant Link column.

docs/staticPage.lua: add a docs-page class to the row wrapper so /docs/-
only CSS can be scoped without affecting other gbsPage static pages.

src/hg/htdocs/staticStyle/gbStatic.css: add scoped .docs-page styles for
the sidebar TOC ("On this page" label) and tables (roomier padding,
zebra striping using the existing tr.even/tr.odd classes, subtle hover).
All new rules are namespaced under .docs-page so the rest of the site is
untouched.

diff --git docs/staticPage.lua docs/staticPage.lua
index 615beda2a3d..31aba84f10c 100644
--- docs/staticPage.lua
+++ docs/staticPage.lua
@@ -1,476 +1,477 @@
 -- UCSC: Slightly modified to produce html that follows the genome browser
 -- static pages conventions
 --
 --
 -- This is a sample custom writer for pandoc.  It produces output
 -- that is very similar to that of pandoc's HTML writer.
 -- There is one new feature: code blocks marked with class 'dot'
 -- are piped through graphviz and images are included in the HTML
 -- output using 'data:' URLs.
 --
 -- Invoke with: pandoc -t staticPage.lua
 --
 
 -- Character escaping
 local function escape(s, in_attribute)
   return s:gsub("[<>&\"']",
     function(x)
       if x == '<' then
         return '&lt;'
       elseif x == '>' then
         return '&gt;'
       elseif x == '&' then
         return '&amp;'
       elseif x == '"' then
         return '&quot;'
       elseif x == "'" then
         return '&#39;'
       else
         return x
       end
     end)
 end
 
 -- Helper function to convert an attributes table into
 -- a string that can be put into HTML tags.
 local function attributes(attr)
   local attr_table = {}
   for x,y in pairs(attr) do
     if y and y ~= "" then
       table.insert(attr_table, ' ' .. x .. '="' .. escape(y,true) .. '"')
     end
   end
   return table.concat(attr_table)
 end
 
 -- Run cmd on a temporary file containing inp and return result.
 local function pipe(cmd, inp)
   local tmp = os.tmpname()
   local tmph = io.open(tmp, "w")
   tmph:write(inp)
   tmph:close()
   local outh = io.popen(cmd .. " " .. tmp,"r")
   local result = outh:read("*all")
   outh:close()
   os.remove(tmp)
   return result
 end
 
 -- Table to store footnotes, so they can be included at the end.
 local notes = {}
 
 -- Table to store headers, so they can be inserted at the end
 local headers = {}
 
 -- flag to see if we have to close a previous div
 local headerOpen = false
 
 -- Blocksep is used to separate block elements.
 function Blocksep()
   return "\n\n"
 end
 
 -- Print contents of `tbl`, with indentation.
 -- `indent` sets the initial level of indentation.
 function tprint (tbl, indent)
   if not indent then indent = 0 end
   for k, v in pairs(tbl) do
     formatting = string.rep("  ", indent) .. k .. ": "
     if type(v) == "table" then
       print(formatting)
       tprint(v, indent+1)
     elseif type(v) == 'boolean' then
       print(formatting .. tostring(v))      
     else
       print(formatting .. v)
     end
   end
 end
 
 -- remove all special chars from the string and remove all html tags
 function simplifyId(idStr)
     idStr=idStr:gsub("%b<>", "")
     idStr = string.lower(string.gsub(idStr, "%s+", "-"))
     idStr = string.lower(string.gsub(idStr, "[^a-zA-z-]", ""))
     return idStr
 end
 
 -- This function is called once for the whole document. Parameters:
 -- body is a string, metadata is a table, variables is a table.
 -- This gives you a fragment.  You could use the metadata table to
 -- fill variables in a custom lua template.  Or, pass `--template=...`
 -- to pandoc, and pandoc will add do the template processing as
 -- usual.
 function Doc(body, metadata, variables)
   local buffer = {}
   local function add(s)
     table.insert(buffer, s)
   end
 
   -- ucsc changes start
   
   -- debugging of meta info:
   -- print("vars")
   -- tprint(variables)
   -- print("meta")
   -- tprint(metadata)
 
 
   if metadata["title"] then
     add("<!DOCTYPE HTML>")
     add("<!-- DO NOT EDIT THE HTDOCS VERSION OF THIS FILE. THIS FILE IS AUTOMATICALLY")
     add("     GENERATED FROM A MARKDOWN FILE IN kent/src/product. MAKE ANY EDITS TO")
     add("     THIS PAGE THERE, THEN RUN MAKE in kent/src/product/mirrorDocs, AND FOLLOW THE")
     add("     INSTRUCTIONS TO COMMIT THIS PAGE INTO git.")
     add("     Please read the file kent/src/product/Note-To-QA.txt for details.")
     add("     -->")
     add("<!--#set var=\"TITLE\" value=\"" .. metadata["title"] .. "\" -->")
     add("<!--#set var=\"ROOT\" value=\"" .. (variables["ROOT"] or metadata["ROOT"] or "..") .. "\" -->")
     add("")
     add("<!-- Relative paths to support mirror sites with non-standard GB docs install -->")
     add("<!--#include virtual=\"$ROOT/inc/gbPageStart.html\" -->")
     add("<link rel=\"stylesheet\" href=\"<!--#echo var=\"ROOT\" -->/style/bootstrap-3-3-7.min.css\">")
     add("")
     add("<h1>" .. metadata["title"] .. "</h1>")
   else
     add("<h1>No title defined in document, first line must be % mytitle </h1>")
   end
 
-  -- Sidebar TOC + body in Bootstrap grid
-  add('<div class="row docs-toc-row">')
+  -- Sidebar TOC + body in Bootstrap grid. The docs-page class scopes
+  -- /docs/-only typography and table styling in gbStatic.css.
+  add('<div class="row docs-toc-row docs-page">')
   add('<div class="col-md-2 hidden-sm hidden-xs">')
   add('<nav class="docs-toc" id="docs-toc">')
   add('<ul>')
   for i, h in ipairs(headers) do
     add("<li><a href='#" .. h.id .. "'>" .. h.text .. "</a></li>")
   end
   add('</ul>')
   add('</nav>')
   add('</div>')
   add('<div class="col-md-10">')
   -- ucsc change end
 
   add(body)
   add('</div>') -- close col-md-10
   add('</div>') -- close row
   if #notes > 0 then
     add('<ol class="footnotes">')
     for _,note in pairs(notes) do
       add(note)
     end
     add('</ol>')
   end
   return table.concat(buffer,'\n') .. '\n'
 end
 
 -- The functions that follow render corresponding pandoc elements.
 -- s is always a string, attr is always a table of attributes, and
 -- items is always an array of strings (the items in a list).
 -- Comments indicate the types of other variables.
 
 function Str(s)
   return escape(s)
 end
 
 function Space()
   return " "
 end
 
 function SoftBreak()
   return "\n"
 end
 
 function LineBreak()
   return "<br/>"
 end
 
 function Emph(s)
   return "<em>" .. s .. "</em>"
 end
 
 function Strong(s)
   return "<strong>" .. s .. "</strong>"
 end
 
 function Subscript(s)
   return "<sub>" .. s .. "</sub>"
 end
 
 function Superscript(s)
   return "<sup>" .. s .. "</sup>"
 end
 
 function SmallCaps(s)
   return '<span style="font-variant: small-caps;">' .. s .. '</span>'
 end
 
 function Strikeout(s)
   return '<del>' .. s .. '</del>'
 end
 
 function obfuscate(s)
    -- obfuscate the email address a la Hiram's encodeEmail.pl 
    local refs = {}
    for i = 1, string.len(s) do
       local ascCode = string.byte(s, i)
       local ref = "&#" .. tostring(ascCode)
       table.insert(refs, ref)
    end
    return table.concat(refs, "")
 end
 
 function Link(s, src, tit, attr)
   local extra = ""
   if string.sub(src, 1, 7)=="mailto:" then
       src = "mailto:" .. obfuscate(string.sub(src, 7), 7)
       -- assume that the link label is an email address if it contains an @ character
       if string.match(s, "%@")~=nil then
           s = obfuscate(s)
       end
   else
       -- absolute URLs open in a new tab; rel="noopener" prevents tabnabbing
       if string.match(src, "^https?://") then
           extra = " target='_blank' rel='noopener'"
       end
       src = escape(src, true)
       tit = escape(tit, true)
   end
 
   if tit and tit ~= "" then
       extra = extra .. " title='" .. tit .. "'"
   end
 
   return "<a href='" .. src .. "'" .. extra .. ">" .. s .. "</a>"
 
 end
 
 function Image(s, src, tit, attr)
   return "<img alt='" .. escape(s,true) .. "' src='" .. escape(src,true) .. "' title='" ..
          escape(tit,true) .. "'/>"
 end
 
 
 function Code(s, attr)
   return "<code" .. attributes(attr) .. ">" .. escape(s) .. "</code>"
 end
 
 function InlineMath(s)
   return "\\(" .. escape(s) .. "\\)"
 end
 
 function DisplayMath(s)
   return "\\[" .. escape(s) .. "\\]"
 end
 
 function SingleQuoted(s)
   return "&lsquo;" .. s .. "&rsquo;"
 end
 
 function DoubleQuoted(s)
   return "&ldquo;" .. s .. "&rdquo;"
 end
 
 function Note(s)
   local num = #notes + 1
   -- insert the back reference right before the final closing tag.
   s = string.gsub(s,
           '(.*)</', '%1 <a href="#fnref' .. num ..  '">&#8617;</a></')
   -- add a list item with the note to the note table.
   table.insert(notes, '<li id="fn' .. num .. '">' .. s .. '</li>')
   -- return the footnote reference, linked to the note.
   return '<a id="fnref' .. num .. '" href="#fn' .. num ..
             '"><sup>' .. num .. '</sup></a>'
 end
 
 function Span(s, attr)
   return "<span" .. attributes(attr) .. ">" .. s .. "</span>"
 end
 
 function Cite(s, cs)
   local ids = {}
   for _,cit in ipairs(cs) do
     table.insert(ids, cit.citationId)
   end
   return "<span class=\"cite\" data-citation-ids=\"" .. table.concat(ids, ",") ..
     "\">" .. s .. "</span>"
 end
 
 function Plain(s)
   return s
 end
 
 function Para(s)
   return "<p>\n" .. s .. "\n</p>"
 end
 
 -- lev is an integer, the header level.
 function Header(lev, s, attr)
   local lines = { }
 
   if lev == 1 then
 
     idStr = simplifyId(s)
 
     table.insert(headers, {text = s, id = idStr})
 
     table.insert(lines, "<h2 id='" .. idStr .. "'>"  .. s .. "</h2>")
     headerOpen = true
 
   elseif lev == 2 then
     -- Collect lev==2 headers for TOC (markdown ## headings)
     local idStr = attr.id or simplifyId(s)
     table.insert(headers, {text = s, id = idStr})
     table.insert(lines, "<h" .. lev .. " id='" .. idStr .. "'" ..  ">" .. s .. "</h" .. lev .. ">")
 
   else
     table.insert(lines, "<h" .. lev .. attributes(attr) ..  ">" .. s .. "</h" .. lev .. ">")
   end
 
   return table.concat(lines, "\n")
 end
 
 function BlockQuote(s)
   return "<blockquote>\n" .. s .. "\n</blockquote>"
 end
 
 function HorizontalRule()
   return "<hr/>"
 end
 
 function CodeBlock(s, attr)
   -- If code block has class 'dot', pipe the contents through dot
   -- and base64, and include the base64-encoded png as a data: URL.
   if attr.class and string.match(' ' .. attr.class .. ' ',' dot ') then
     local png = pipe("base64", pipe("dot -Tpng", s))
     return '<img src="data:image/png;base64,' .. png .. '"/>'
   -- otherwise treat as code (one could pipe through a highlighter)
   else
     return "<pre><code" .. attributes(attr) .. ">" .. escape(s) ..
            "</code></pre>"
   end
 end
 
 function BulletList(items)
   local buffer = {}
   for _, item in pairs(items) do
     table.insert(buffer, "<li>" .. item .. "</li>")
   end
   return "<ul>\n" .. table.concat(buffer, "\n") .. "\n</ul>"
 end
 
 function OrderedList(items)
   local buffer = {}
   for _, item in pairs(items) do
     table.insert(buffer, "<li>" .. item .. "</li>")
   end
   return "<ol>\n" .. table.concat(buffer, "\n") .. "\n</ol>"
 end
 
 -- Revisit association list STackValue instance.
 function DefinitionList(items)
   local buffer = {}
   for _,item in pairs(items) do
     for k, v in pairs(item) do
       table.insert(buffer,"<dt>" .. k .. "</dt>\n<dd>" ..
                         table.concat(v,"</dd>\n<dd>") .. "</dd>")
     end
   end
   return "<dl>\n" .. table.concat(buffer, "\n") .. "\n</dl>"
 end
 
 -- Convert pandoc alignment into a style attribute fragment for HTML5.
 -- align is AlignLeft, AlignRight, AlignCenter, or AlignDefault. Left is the
 -- default cell alignment, so emit nothing in that case.
 function html_align_style(align)
   if align == 'AlignRight' then
     return ' style="text-align: right"'
   elseif align == 'AlignCenter' then
     return ' style="text-align: center"'
   else
     return ''
   end
 end
 
 function CaptionedImage(src, tit, caption)
    return '<div class="figure">\n<img src="' .. escape(src,true) ..
       '" title="' .. escape(tit,true) .. '"/>\n' ..
       '<p class="caption">' .. caption .. '</p>\n</div>'
 end
 
 -- Caption is a string, aligns is an array of strings,
 -- widths is an array of floats, headers is an array of
 -- strings, rows is an array of arrays of strings.
 function Table(caption, aligns, widths, headers, rows)
   local buffer = {}
   local function add(s)
     table.insert(buffer, s)
   end
   add("<table>")
   if caption ~= "" then
     add("<caption>" .. caption .. "</caption>")
   end
   if widths and widths[1] ~= 0 then
     for _, w in pairs(widths) do
       add('<col style="width: ' .. string.format("%.0f%%", w * 100) .. '">')
     end
   end
   local header_row = {}
   local empty_header = true
   for i, h in pairs(headers) do
     table.insert(header_row,'<th' .. html_align_style(aligns[i]) .. '>' .. h .. '</th>')
     empty_header = empty_header and h == ""
   end
   if empty_header then
     head = ""
   else
     add('<tr class="header">')
     for _,h in pairs(header_row) do
       add(h)
     end
     add('</tr>')
   end
   local class = "even"
   for _, row in pairs(rows) do
     class = (class == "even" and "odd") or "even"
     add('<tr class="' .. class .. '">')
     for i,c in pairs(row) do
       add('<td' .. html_align_style(aligns[i]) .. '>' .. c .. '</td>')
     end
     add('</tr>')
   end
   add('</table>')
   return table.concat(buffer,'\n')
 end
 
 function RawInline(format, str)
   if format == "html" then
     return str
   else
     --- not sure what to do here for PDF or ebook output... ---
     return str
   end
 end
 
 function RawBlock(format, str)
   if format == "html" then
     return str
   else
     return ''
   end
 end
 
 function Div(s, attr)
   return "<div" .. attributes(attr) .. ">\n" .. s .. "</div>"
 end
 
 -- The following code will produce runtime warnings when you haven't defined
 -- all of the functions you need for the custom writer, so it's useful
 -- to include when you're working on a writer.
 local meta = {}
 meta.__index =
   function(_, key)
     io.stderr:write(string.format("WARNING: Undefined function '%s'\n",key))
     return function() return "" end
   end
 setmetatable(_G, meta)