82b12a5fae1c82dffe13401e09749849d116e724 lrnassar Fri Dec 5 17:27:44 2025 -0800 Making major changes to the markdown /docs/ directory since we are going to keep adding to it. Starting with adding more heirarchy, also had to update the makefile and staticPage.lua to reference the correct root path for the CSS. Also had to update all of the relative links in the pages so far in order to make them absolute paths for easier implementation. Lastly, adding the new hubBasics page which is the first in the new hubs subdir. Refs #28347 diff --git docs/staticPage.lua docs/staticPage.lua index 34a4ba7859f..01bd9f45fcd 100644 --- docs/staticPage.lua +++ docs/staticPage.lua @@ -1,456 +1,456 @@ -- 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 '<' elseif x == '>' then return '>' elseif x == '&' then return '&' elseif x == '"' then return '"' elseif x == "'" then return ''' 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=\"..\" -->") + 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 for i, h in ipairs(headers) do idStr = simplifyId(h) add("<h6><a href='#" .. idStr .. "'>" .. h .. "</a></h6>") end -- ucsc change end add(body) 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) 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 src = escape(src, true) tit = escape(tit, true) s = escape(s, true) end return "<a href='" .. src .. "' title='" .. tit .. "'>" .. s .. "</a>" end function Image(s, src, tit, attr) return "<img 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 "‘" .. s .. "’" end function DoubleQuoted(s) return "“" .. s .. "”" 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 .. '">↩</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, s) table.insert(lines, "<a name='" .. idStr .. "'></a>") table.insert(lines, "<h2>" .. s .. "</h2>") headerOpen = true 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 to something HTML can use. -- align is AlignLeft, AlignRight, AlignCenter, or AlignDefault. function html_align(align) if align == 'AlignLeft' then return 'left' elseif align == 'AlignRight' then return 'right' elseif align == 'AlignCenter' then return 'center' else return 'left' 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 width="' .. string.format("%d%%", w * 100) .. '" />') end end local header_row = {} local empty_header = true for i, h in pairs(headers) do local align = html_align(aligns[i]) table.insert(header_row,'<th align="' .. align .. '">' .. 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 align="' .. html_align(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)