6cf524b43a05ac1bea2cfd20cd43a10d67e843c9
jnavarr5
  Thu Jun 25 17:29:43 2026 -0700
Document how to add a new FreeType font to hgTracks in the mirror manual, and correct the default freeTypeDir path, refs #37698

diff --git src/hg/htdocs/goldenPath/help/mirrorManual.html src/hg/htdocs/goldenPath/help/mirrorManual.html
index a0bb41110af..82ac240ac93 100755
--- src/hg/htdocs/goldenPath/help/mirrorManual.html
+++ src/hg/htdocs/goldenPath/help/mirrorManual.html
@@ -20,30 +20,31 @@
 <h6><a href='#installing-the-ucsc-genome-browser'>Installing the UCSC Genome browser</a></h6>
 <h6><a href='#mariadb-setup'>MariaDB Setup</a></h6>
 <h6><a href='#local-git-repository-aka-quotthe-source-treequot'>Local Git repository (aka: &quot;the source tree&quot;)</a></h6>
 <h6><a href='#adding-your-own-track-groups-to-the-browser'>Adding your own track groups to the browser</a></h6>
 <h6><a href='#adding-your-own-tracks-to-the-browser'>Adding your own tracks to the browser</a></h6>
 <h6><a href='#adding-a-new-custom-non-ucsc-genome-to-the-browser'>Adding a new, custom (non-UCSC) genome to the browser</a></h6>
 <h6><a href='#modifying-the-source-code'>Modifying the source code</a></h6>
 <h6><a href='#custom-track-database'>Custom Track Database</a></h6>
 <h6><a href='#debugging-the-cgi-binaries'>Debugging the CGI binaries</a></h6>
 <h6><a href='#notes-on-security'>Notes on security</a></h6>
 <h6><a href='#proxy-support'>Proxy support</a></h6>
 <h6><a href='#support-for-cloud-urls'>Support for cloud URLs</a></h6>
 <h6><a href='#the-udc-local-cache-directory'>The UDC local cache directory</a></h6>
 <h6><a href='#activating-cram-support-for-the-genome-browser'>Activating CRAM support for the Genome Browser.</a></h6>
 <h6><a href='#using-freetype-font-support-for-anti-aliased-text'>Using FreeType font support for anti-aliased text</a></h6>
+<h6><a href='#adding-a-new-font-to-the-genome-browser-display'>Adding a new font to the Genome Browser display</a></h6>
 <h6><a href='#building-the-kent-source-tree'>Building the kent source tree.</a></h6>
 <h6><a href='#adding-a-track-hub-to-your-hubpublic-table-so-it-appears-under-my-data-gt-track-hubs'>Adding a track hub to your hubPublic table so it appears under My Data &gt; Track Hubs</a></h6>
 <h6><a href='#make-the-api-work-in-the-same-way-as-on-the-public-website'>Make the API work in the same way as on the public website</a></h6>
 <h6><a href='#set-up-the-cloudflare-captcha'>Set up the Cloudflare captcha</a></h6>
 <p>
 We do not recommend following the procedure below anymore, as we provide a docker image and
 the &quot;GBIC&quot; installation bash script. They can setup a genome browser with
 a single linux command line and within a few minutes. This page exists as a
 reference, explains how the installer is structured and helps changing the
 configuration files once your genome browser is running. If you run into
 trouble with any of these steps, do not hesitate to contact us so we can improve this page.
 </p>
 
 <a name='overview-of-the-genome-browser-directories-and-databases'></a>
 <h2>Overview of the Genome Browser directories and databases</h2>
@@ -2145,34 +2146,35 @@
 
 <pre><code>/usr/share/X11/fonts/urw-fonts
 /usr/share/fonts/default/Type1
 /usr/share/fonts/type1/gsfonts</code></pre>
 
 <p>
 To turn on the FreeType font rendering you need to add this line to your hg.conf file:
 </p>
 
 <pre><code>freeType=on</code></pre>
 
 <p>
 By default, the Genome Browser looks in the directory
 </p>
 
-<pre><code>/usr/share/fonts/default/Type1 </code></pre>
+<pre><code>../htdocs/urw-fonts</code></pre>
 
 <p>
-for the font files it expects to find. If you have these fonts in a different directory, you need
+for the font files it expects to find. (This path is relative to the CGI working
+directory, so it resolves to the shared htdocs/urw-fonts directory.) If you have these fonts in a different directory, you need
 to add this line to your hg.conf file:
 </p>
 
 <pre><code>freeTypeDir=&#39;&lt;apache accessible directory path with fonts in it&gt;&#39;</code></pre>
 
 <p>
 The names of the font files that the Genome Browser expects and their md5sums are in the following table:
 </p>
 
 <pre><code>5624bc04bbd862287bda3c44b15e90d6  a010013l.pfb
 6883f53d0d140f972480f179bb5e4e3b  a010015l.pfb
 db21f79bac990fa7e3de6d4cc6f54020  a010033l.pfb
 c3d0c3af6bc183010204ca923fb98e83  a010035l.pfb
 33265074c9c45c356f90de9cc47259b3  n019003l.pfb
 9d07b8658622c2e0127628c87fdb9661  n019004l.pfb
@@ -2180,30 +2182,89 @@
 9f2d4377d9eea95dfdfa705c83a39464  n019024l.pfb
 8f75382bd2620a20aaeb06ab8c591e8f  n019043l.pfb
 28bb40d1700909b2509e2125a1963e2c  n019044l.pfb
 adf4d5565bec1170f0a5810c6984ff55  n019063l.pfb
 57e1a49c39a546c2883375df12111816  n019064l.pfb
 84e347c88eff2e77ed40b020b457bafe  n021003l.pfb
 8721c1175d907d7d484bdaa91d4533ad  n021004l.pfb
 eef0367afaa10b929e528c40c980b941  n021023l.pfb
 7af41ff3536fadcdc27eb9e5cc1c32d3  n021024l.pfb
 db95b702b81c12df1f91d15c8a6c3191  n022003l.pfb
 e97c9af68414fabe157af711b7691df7  n022004l.pfb
 f13fb8e581426a1ffa5fc12b10ad0f34  n022023l.pfb
 f3cd9244150f086434b62d5c5bb559b0  n022024l.pfb
 30aef717b7c68a6b6b7760b764fbd01c  z003034l.pfb</code></pre>
 
+<a name='adding-a-new-font-to-the-genome-browser-display'></a>
+<h2>Adding a new font to the Genome Browser display</h2>
+
+<p>
+The fonts offered in the hgTracks &quot;configure&quot; page Font menu are defined in a
+table in the source code: the <code>freeTypeFonts[]</code> array in
+<a href='https://raw.githubusercontent.com/ucscGenomeBrowser/kent/refs/heads/master/src/hg/hgTracks/config.c' title=''>&lt;code&gt;src/hg/hgTracks/config.c&lt;/code&gt;</a>.
+Adding a font is therefore a source code change, and
+you will need to rebuild the CGIs afterward (see &quot;Building the kent source tree&quot;,
+below). There are two steps.
+</p>
+
+<ol>
+<li><p>
+Put the font file where the rendering engine can find it. At run time the
+file is looked up under the directory given by the <code>freeTypeDir</code> setting in
+hg.conf, which defaults to <code>../htdocs/urw-fonts</code>. That path is relative to the
+CGI working directory, so it resolves to the shared <code>htdocs/urw-fonts</code>
+directory even when you run from a per-user sandbox; you do not need a copy
+under your own htdocs. Both Type1 (<code>.pfb</code>) and TrueType (<code>.ttf</code>) font files
+are supported.
+</p></li>
+<li><p>
+Add a row to the <code>freeTypeFonts[]</code> table in <code>src/hg/hgTracks/config.c</code>,
+giving the name to display and the font file name, for example:
+</p>
+
+<pre><code>{&quot;Lexend&quot;,      &quot;Lexend-Regular.ttf&quot;},
+{&quot;Lexend-Bold&quot;, &quot;Lexend-Bold.ttf&quot;},</code></pre>
+
+<p>
+The name is what appears in the configure-page Font menu. The configure page
+splits the name on the first &quot;-&quot; into a face and a style: the part before the
+&quot;-&quot; is the face shown in the Font menu, and the part after is an entry in the
+Style menu. A plain weight is just the face name (Lexend); a variant is
+written as Face-Style (Lexend-Bold). Group a face&#39;s variants on consecutive
+rows so the Style menu lists them together.
+</p></li>
+</ol>
+
+<p>
+A couple of things to watch out for:
+</p>
+
+<ul>
+<li><p>
+Avoid variable fonts (for example InterVariable.ttf). The engine opens face
+index 0 with no named instance selected, so a variable font renders only its
+default master, which is usually not the weight you expected. The symptom is
+that the new option appears in the menu but a different font is drawn. Use a
+static, single-weight file instead (for example Inter-Regular.ttf).
+</p></li>
+<li><p>
+The menu name must match the table exactly, including the face/style split
+described above. If a selected name matches no row in the table, the browser
+silently falls back to the old bitmap font engine.
+</p></li>
+</ul>
+
 <a name='building-the-kent-source-tree'></a>
 <h2>Building the kent source tree.</h2>
 
 <p>
 In some cases, you may have to modify the source code itself. In these cases, you would need
 to build all the tools and CGI programs from the source code on your machine.
 </p>
 
 <p>
 There are scripts available in the git repo src/product/scripts/ directory
 that can run all of these steps for you with the script: scripts/kentSrcUpdate.sh
 See the instructions in scripts/README
 </p>
 
 <p>