Fossil

Check-in [9044fd2dbe]
Login
☰Home Timeline Docs Forum Download

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:The www/customskin.md document hadn't been updated since we removed the explicit <html><head> stuff from the default skins and moved that into the C code so we could insert the CSP and such automatically. Updated it to show the inner <div> tags that you actually get by default now, and talked about how the HTML document wrapper is added automatically. Also fixed some spelling and grammar errors.
Downloads: Tarball | ZIP archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: 9044fd2dbe7a8ac02ae2d976b50f40fd4a75357bd3cb2be73df83c371cc55b14
User & Date: wyoung 2019-08-19 01:17:06.711
References
2019-08-20
04:57
Fixed an unwanted "$nonce" variable expansion within the new customskin.md introduced by [9044fd2dbe] which only occurs *sometimes*: not on fossil-scm.org, and apparently not in my earlier ckout testing prior to checking it in, but now in a different ckout test. This has to be a TH1 thing, but I don't understand why we didn't see this earlier. This is just a workaround for the symptom. ... (check-in: 9bdf650f0b user: wyoung tags: trunk)
Context
2019-08-19
13:04
Increase the default HTTP request timeout to 10 minutes. Provide the FOSSIL_DEFAULT_TIMEOUT compile-time option for setting an alternative default. ... (check-in: 7979989dff user: drh tags: trunk)
01:17
The www/customskin.md document hadn't been updated since we removed the explicit <html><head> stuff from the default skins and moved that into the C code so we could insert the CSP and such automatically. Updated it to show the inner <div> tags that you actually get by default now, and talked about how the HTML document wrapper is added automatically. Also fixed some spelling and grammar errors. ... (check-in: 9044fd2dbe user: wyoung tags: trunk)
00:51
Fix embedded HTML detection for the 'doc' web page when the 'data-title' attribute is not specified. ... (check-in: 3d6a4fd95c user: mistachkin tags: trunk)
Changes
Unified Diff Ignore Whitespace Patch
Changes to www/customskin.md. 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18


19
20
21
22
23
24


25
26
27


28


29
30

31


32

33




34

35

36
37
38
39
40
41
42
43


44
45
46
47
48
49
50

Theming
=======

Every HTML page generated by Fossil has the following basic structure:

<blockquote><table border=1 cellpadding=10><tbody>
<tr><td style='background-color:lightblue;text-align:center;'>Header</td></tr>
<tr><td style='background-color:lightgreen;text-align:center;'>
Fossil-Generated Content</td></tr>
<tr><td style='background-color:lightblue;text-align:center;'>Footer</td></tr>
<tr><td style='background-color:lightyellow;text-align:center;'>Javascript (optional)</td></tr>
</tbody></table></blockquote>

The header and footer control the "look" of Fossil pages.  Those
two sections can be customized separately for each repository to
develop a new theme.

The header will normally look something like this:



        <html>
        <head> ... </head>
        <body>
        ... top banner and menu bar ...
        <div class='content'>



And the footer will look something like this:



        </div>


        ... bottom material ...
        </body>

        </html>




The &lt;head&gt; element in the header will normally reference the




/style.css CSS file that Fossil stores internally.  (The $stylesheet_url

TH1 variable, described below, is useful for accomplishing this.)


The middle "content" section comprised the bulk of most pages and
contains the actual Fossil-generated data
that the user is interested in seeing.  The text of this content
section is not normally configurable.  The content text can be styled
using CSS, but it otherwise fixed.  Hence it is the header and footer
and the CSS that determine the look of a repository.
We call the bundle of built-in CSS, header, and footer a "skin".



Built-in Skins
--------------

Fossil comes with several built-in skins.  The sources to these built-ins can
be found in the Fossil source tree under the skins/ folder.  The skins/
folder contains a separate subfolder for each built-in skin, with each














|
<
<

|
>
>

|
|
<
<
|
>
>

|

>
>

>
>
|
|
>
|
>
>

>
|
>
>
>
>
|
>
|
>

|



|


>
>








1
2
3
4
5
6
7
8
9
10
11
12
13
14


15
16
17
18
19
20
21


22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66

Theming
=======

Every HTML page generated by Fossil has the following basic structure:

<blockquote><table border=1 cellpadding=10><tbody>
<tr><td style='background-color:lightblue;text-align:center;'>Header</td></tr>
<tr><td style='background-color:lightgreen;text-align:center;'>
Fossil-Generated Content</td></tr>
<tr><td style='background-color:lightblue;text-align:center;'>Footer</td></tr>
<tr><td style='background-color:lightyellow;text-align:center;'>Javascript (optional)</td></tr>
</tbody></table></blockquote>

The default header looks something like this:



        <div class="header">
          <div class="title"><h1>$<project_name></h1>$<title></div>
          ... top banner and menu bar ...

The Fossil-generated content section looks like this:



        <div class="content">
          ... generated content here ...
        </div>

And the footer looks like this:

        <div class="footer">
          ... skin-specific stuff here ...
        </div>
        <script nonce="$nonce">
          <th1>styleScript</th1>
        </script>

Notice that there are no `<html>` or `<head>` elements in the header,
nor is there an `</html>` closing tag in the footer.  Fossil generates
this material automatically unless it sees that you have provided your
own HTML document header within the skin’s Header section.

This design lets most users get the benefit of Fossil’s automatic HTML
document header, which takes care of quite a few different things for
you, while still allowing you to override if at need. For example, you
might not agree with Fossil’s default [Content Security Policy][csp]
which gets set in a `<meta>` tag within this default document header, so
you could provide your own, which would suppress that code.

When overriding the default document header, you might want to use some
of the TH1 variables documented below such as `$stylesheet_url`
to avoid hand-writing code that Fossil can generate for you.

The middle "content" section comprises the bulk of most pages and
contains the actual Fossil-generated data
that the user is interested in seeing.  The text of this content
section is not normally configurable.  The content text can be styled
using CSS, but it is otherwise fixed.  Hence it is the header, the footer,
and the CSS that determine the look of a repository.
We call the bundle of built-in CSS, header, and footer a "skin".

[csp]: https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP

Built-in Skins
--------------

Fossil comes with several built-in skins.  The sources to these built-ins can
be found in the Fossil source tree under the skins/ folder.  The skins/
folder contains a separate subfolder for each built-in skin, with each
︙︙
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133

134
135
136
137





138
139
140
141
142
143
144

will provide an historical record of what the skin used to be and
allow the historical look of the repositories to be recreated if
necessary.

When cloning a repository, the skin of new repository is initialized to
the skin of the repository from which it was cloned.

Header And Footer Processing
----------------------------

The header.txt and footer.txt files of a skin are merely the HTML text
of the header and footer.  Except, before being prepended and appended to
the content, the header and footer text are run through a
[TH1 interpreter](./th1.md) that might adjust the text as follows:

  *  All text within &lt;th1&gt;...&lt;/th1&gt; is elided from the
     output and that text is instead run as a TH1 script.  That TH1
     script has the opportunity to insert new text in place of itself,
     or to inhibit or enable the output of subsequent text.

  *  Text for the form "$NAME" or "$&lt;NAME&gt;" is replace with
     the value of the TH1 variable NAME.

For example, the following is the first few lines of a typical
header file:

       <html>
        <head>
         <base href="$baseurl/$current_page" />
         <title>$<project_name>: $<title></title>
         <link rel="alternate" type="application/rss+xml" title="RSS Feed"
               href="$home/timeline.rss" />
         <link rel="stylesheet" href="$stylesheet_url" type="text/css"
               media="screen" />
       </head>

After variables are substituted by TH1, the final header text
delivered to the web browser might look something like this:

        <html>
         <head>
          <base href="https://www.fossil-scm.org/skin2/timeline" />
          <title>Fossil: Timeline</title>
          <link rel="alternate" type="application/rss+xml" title="RSS Feed"
                href="/skin2/timeline.rss" />
          <link rel="stylesheet" href="/skin2/style.css?default" type="text/css"
                media="screen" />
         </head>


The same TH1 interpreter is used for both the header and the footer
and for all scripts contained within them both.  Hence, any global
TH1 variables that are set by the header are available to the footer.






Customizing the ≡ Hamburger Menu
--------------------------------

The menu bar of the default skin has an entry to open a drop-down menu with
additional navigation links, represented by the ≡ button (hence the name
"hamburger menu"). The Javascript logic to open and close the hamburger menu








|


|
|
|







|


|
<

<
|
<
|
<
<
<
<
<

|
<

<
|
<
|
|
<
<
<
<
>




>
>
>
>
>








102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125

126

127

128





129
130

131

132

133
134




135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151

will provide an historical record of what the skin used to be and
allow the historical look of the repositories to be recreated if
necessary.

When cloning a repository, the skin of new repository is initialized to
the skin of the repository from which it was cloned.

Header and Footer Processing
----------------------------

The `header.txt` and `footer.txt` files of a skin are merely the HTML text
of the header and footer, except that before being prepended and appended to
the content, their text content is run through a
[TH1 interpreter](./th1.md) that might adjust the text as follows:

  *  All text within &lt;th1&gt;...&lt;/th1&gt; is elided from the
     output and that text is instead run as a TH1 script.  That TH1
     script has the opportunity to insert new text in place of itself,
     or to inhibit or enable the output of subsequent text.

  *  Text of the form "$NAME" or "$&lt;NAME&gt;" is replaced with
     the value of the TH1 variable NAME.

Above, we saw the first few lines of a typical header file:



        <div class="header">

          <div class="title"><h1>$<project_name></h1>$<title>/div>






After variables are substituted by TH1, that will look more like this:



        <div class="header">

          <div class="title"><h1>Project Name</h1>Page Title</div>





As you can see, two TH1 variable substitutions were done.

The same TH1 interpreter is used for both the header and the footer
and for all scripts contained within them both.  Hence, any global
TH1 variables that are set by the header are available to the footer.

As pointed out at the start of this document, Fossil provides the HTML
document container tags `<html>`, `<head>`, and their inner content when
your skin’s header and footer don’t include them.


Customizing the ≡ Hamburger Menu
--------------------------------

The menu bar of the default skin has an entry to open a drop-down menu with
additional navigation links, represented by the ≡ button (hence the name
"hamburger menu"). The Javascript logic to open and close the hamburger menu
︙︙
This page was generated in about 0.018s by Fossil 2.26 [1205ec86cb] 2025-04-30 16:57:32