Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,27 @@ hugo server --bind 0.0.0.0 # run the server

You can now preview the site locally on http://localhost:1313/

# Changing the docsy templates
Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This explains how to compare the template overrides to the originals


The Docsy theme templates are downloaded to the local go cache.
For example `~/go/pkg/mod/github.com/google/docsy\@v0.12.0/`

Overrides to the default docsy templates are in the [layouts] directory. For
example, [layouts/partials] contains the partial templates for HTML pages.

To make a change to the docsy templates, copy the template you want to change
from the docsy module to the `layouts` directory and then make your changes
there. This makes it easier to keep track of the changes we have made to the
templates and to update the docsy module when needed.

For example to see the difference between the default docsy navbar and
the one used in this website with a command such as:

```shell
diff -du ~/go/pkg/mod/github.com/google/docsy\@v0.12.0/layouts/_partials/navbar.html layouts/partials/navbar.html
```


# Release Process

To create documentation for a new release of `parquet-format` create a new <releaseNumber>.md file under `content/en/blog/parquet-format`. Please see existing files in that directory as an example.
Expand Down
68 changes: 68 additions & 0 deletions layouts/partials/head.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
{{/* cSpell:ignore docsearch opengraph outputformat */ -}}
Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks like a huge diff, but the diff from the actual template is quite small. I explained how to compute the difference in README.md. You can see it here:

andrewlamb@Andrews-MacBook-Pro-3:~/Software/parquet-site$ diff -du ~/go/pkg/mod/github.com/google/docsy\@v0.12.0/layouts/_partials/head.html layouts/partials/head.html
--- /Users/andrewlamb/go/pkg/mod/github.com/google/docsy@v0.12.0/layouts/_partials/head.html	2026-02-11 07:27:43
+++ layouts/partials/head.html	2026-02-11 09:32:08
@@ -27,9 +27,9 @@
 {{ partial "twitter_cards.html" . -}}
 {{ partialCached "head-css.html" . "head-css-cache-key" -}}
 <script
-  src="https://code.jquery.com/jquery-3.7.1.min.js"
+  src='{{ "vendor/jquery/jquery-3.7.1.min.js" | relURL }}'
   integrity="sha512-v2CJ7UaYy4JwqLDIrZUI/4hqeoQieOmAZNXBeQyjo21dadnwR+8ZaIJVT8EE2iyI61OV8e6M8PP2/4hpQINQ/g=="
-  crossorigin="anonymous"></script>
+></script>
 {{ if .Site.Params.offlineSearch -}}
 <script defer
   src="https://unpkg.com/lunr@2.3.9/lunr.min.js"
@@ -53,9 +53,9 @@
 {{ define "algolia/head" -}}

 {{ if and .Site.Params.search (isset .Site.Params.search "algolia") -}}
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@docsearch/css@3.8.2"
+<link rel="stylesheet" href='{{ "vendor/docsearch/docsearch-3.8.2.css" | relURL }}'
   integrity="sha512-l7pkV1dOURFyHCeH8I4fK9lCkQKuqhlsTCqRl3zktifDlB8oTUJ+mJPgYkK9kHpUut8j1iPquTv32t6hvTPv3g=="
-  crossorigin="anonymous" />
+/>
 {{ end -}}

 {{ if ne .Site.Params.algolia_docsearch nil -}}

Note the integrity hash is still the same (e.g. integrity="sha512-v2CJ7UaYy4JwqLDIrZUI/4hqeoQieOmAZNXBeQyjo21dadnwR+8ZaIJVT8EE2iyI61OV8e6M8PP2/4hpQINQ/g==")

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have another proposal here to vendor the entire docsy template so it is easier to find / understand

<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
{{ range .AlternativeOutputFormats -}}
<link rel="{{ .Rel }}" type="{{ .MediaType.Type }}" href="{{ .Permalink | safeURL }}">
{{ end -}}

{{ $outputFormat := partial "outputformat.html" . -}}
{{ if and hugo.IsProduction (ne $outputFormat "print") -}}
<meta name="robots" content="index, follow">
{{ else -}}
<meta name="robots" content="noindex, nofollow">
{{ end -}}

{{ partialCached "favicons.html" . }}
<title>
{{- if .IsHome -}}
{{ .Site.Title -}}
{{ else -}}
{{ with .Title }}{{ . }} | {{ end -}}
{{ .Site.Title -}}
{{ end -}}
</title>
<meta name="description" content="{{ partial "page-description.html" . }}">
{{ partial "opengraph.html" . -}}
{{ partial "schema.html" . -}}
{{ partial "twitter_cards.html" . -}}
{{ partialCached "head-css.html" . "head-css-cache-key" -}}
<!-- use vendored copy to avoid cross site restrictions. See https://github.com/apache/parquet-site/pull/160 -->
<script
src='{{ "vendor/jquery/jquery-3.7.1.min.js" | relURL }}'
integrity="sha512-v2CJ7UaYy4JwqLDIrZUI/4hqeoQieOmAZNXBeQyjo21dadnwR+8ZaIJVT8EE2iyI61OV8e6M8PP2/4hpQINQ/g=="
></script>
{{ if .Site.Params.offlineSearch -}}
<script defer
src="https://unpkg.com/lunr@2.3.9/lunr.min.js"
integrity="sha384-203J0SNzyqHby3iU6hzvzltrWi/M41wOP5Gu+BiJMz5nwKykbkUx8Kp7iti0Lpli"
crossorigin="anonymous"></script>
{{ end -}}

{{ if .Site.Params.prism_syntax_highlighting -}}
<link rel="stylesheet" href="{{ "css/prism.css" | relURL }}"/>
{{ end -}}

{{ template "algolia/head" . -}}

{{ partial "hooks/head-end.html" . -}}

{{/* To comply with GDPR, cookie consent scripts places in head-end must execute before Google Analytics is enabled */ -}}
{{ if hugo.IsProduction -}}
{{ partial "google_analytics.html" . -}}
{{ end -}}

{{ define "algolia/head" -}}

{{ if and .Site.Params.search (isset .Site.Params.search "algolia") -}}
<!-- use vendored copy to avoid cross site restrictions. See https://github.com/apache/parquet-site/pull/160 -->
<link rel="stylesheet" href='{{ "vendor/docsearch/docsearch-3.8.2.css" | relURL }}'
integrity="sha512-l7pkV1dOURFyHCeH8I4fK9lCkQKuqhlsTCqRl3zktifDlB8oTUJ+mJPgYkK9kHpUut8j1iPquTv32t6hvTPv3g=="
/>
{{ end -}}

{{ if ne .Site.Params.algolia_docsearch nil -}}
{{ warnf `Config 'params.algolia_docsearch' is deprecated: use 'params.search.algolia'
For details, see https://www.docsy.dev/docs/adding-content/search/#algolia-docsearch.` -}}
{{ end -}}

{{ end -}}
10 changes: 0 additions & 10 deletions layouts/partials/hooks/body-end.html

This file was deleted.

3 changes: 0 additions & 3 deletions layouts/partials/hooks/head-end.html

This file was deleted.

94 changes: 94 additions & 0 deletions layouts/partials/scripts.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,94 @@
{{ $needKaTeX := or .Params.math .Site.Params.katex.enable .Params.chem .Site.Params.chem (.Page.Store.Get "hasKaTeX") (.Page.Store.Get "hasmhchem") -}}
Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Likewise here is the actual diff of this file compared to the template base

andrewlamb@Andrews-MacBook-Pro-3:~/Software/parquet-site$ diff -du ~/go/pkg/mod/github.com/google/docsy\@v0.12.0/layouts/_partials/scripts.html layouts/partials/scripts.html
--- /Users/andrewlamb/go/pkg/mod/github.com/google/docsy@v0.12.0/layouts/_partials/scripts.html	2026-02-11 07:27:43
+++ layouts/partials/scripts.html	2026-02-11 09:32:58
@@ -77,9 +77,8 @@
 {{ partial "hooks/body-end.html" . -}}

 {{ define "algolia/scripts" -}}
-<script src="https://cdn.jsdelivr.net/npm/@docsearch/js@3.8.2"
-  integrity="sha512-lsD+XVzdBI6ZquXc8gqbw0/bgrfIsMJwY/8xvmvbN+U3gZSeG7BXQoCq4zv/yCmntR2GLHtgB+bD4ESPsKIbIA=="
-  crossorigin="anonymous" ></script>
+<script src='{{ "vendor/docsearch/docsearch-3.8.2.min.js" | relURL }}'
+  integrity="sha512-lsD+XVzdBI6ZquXc8gqbw0/bgrfIsMJwY/8xvmvbN+U3gZSeG7BXQoCq4zv/yCmntR2GLHtgB+bD4ESPsKIbIA=="></script>
 <script type="text/javascript">
 const containers = ['#docsearch-0', '#docsearch-1'];
 for (let c of containers) {

Again note integrity is the same

{{ $needmhchem := or .Params.chem .Site.Params.katex.mhchem.enable (.Page.Store.Get "hasmhchem") -}}

{{ if .Site.Params.markmap.enable -}}
<style>
.markmap > svg {
width: 100%;
height: 300px;
}
</style>
<script>
window.markmap = {
autoLoader: {
manual: true,
onReady() {
const { autoLoader, builtInPlugins } = window.markmap;
autoLoader.transformPlugins = builtInPlugins.filter(plugin => plugin.name !== 'prism');
},
},
};
</script>
<script src="https://cdn.jsdelivr.net/npm/markmap-autoloader"></script>
{{ end -}}

{{ if .Site.Params.plantuml.enable -}}
<script src='{{ "js/deflate.js" | relURL }}'></script>
{{ end -}}

{{ if $needKaTeX -}}
{{ partial "scripts/katex.html" (dict "mhchem" $needmhchem) -}}
{{ end -}}

{{ $jsBs := resources.Get "vendor/bootstrap/dist/js/bootstrap.bundle.js" -}}
{{ $jsBase := resources.Get "js/base.js" -}}
{{ $jsSearch := resources.Get "js/search.js" | resources.ExecuteAsTemplate "js/search.js" .Site.Home -}}
{{ $jsMarkmap := resources.Get "js/markmap.js" | resources.ExecuteAsTemplate "js/markmap.js" . -}}
{{ $jsPlantuml := resources.Get "js/plantuml.js" | resources.ExecuteAsTemplate "js/plantuml.js" . -}}
{{ $jsDrawio := resources.Get "js/drawio.js" | resources.ExecuteAsTemplate "js/drawio.js" . -}}
{{ if .Site.Params.offlineSearch -}}
{{ $jsSearch = resources.Get "js/offline-search.js" -}}
{{ end -}}

{{ $jsArray := slice $jsBs $jsBase $jsSearch $jsPlantuml $jsMarkmap $jsDrawio -}}

{{ if .Page.Store.Get "hasmermaid" -}}
{{- partial "scripts/mermaid.html" . -}}
{{ end -}}

{{ if .Site.Params.ui.showLightDarkModeMenu -}}
{{ $jsArray = $jsArray | append (resources.Get "js/dark-mode.js") -}}
{{ end -}}

{{ $js := $jsArray | resources.Concat "js/main.js" -}}
{{ if hugo.IsProduction -}}
{{ $js := $js | minify | fingerprint -}}
<script src="{{ $js.RelPermalink }}" integrity="{{ $js.Data.Integrity }}" crossorigin="anonymous"></script>
{{ else -}}
<script src="{{ $js.RelPermalink }}"></script>
{{ end -}}

{{ if .Site.Params.prism_syntax_highlighting -}}
<script src='{{ "js/prism.js" | relURL }}'></script>
{{ else if ( not .Site.Params.disable_click2copy_chroma ) -}}
{{ $c2cJS := resources.Get "js/click-to-copy.js" -}}
{{ if hugo.IsProduction -}}
{{ $c2cJS = $c2cJS | minify | fingerprint -}}
{{ end -}}
<script defer src="{{ $c2cJS.RelPermalink }}" {{ with $c2cJS.Data.Integrity -}}
integrity="{{ . }}" {{ end -}}
crossorigin="anonymous"></script>
{{ end -}}

{{ if and .Site.Params.search (isset .Site.Params.search "algolia") -}}
{{ template "algolia/scripts" .Site.Params.search.algolia -}}
{{ end -}}
<script src='{{ "js/tabpane-persist.js" | relURL }}'></script>
{{ partial "hooks/body-end.html" . -}}

{{ define "algolia/scripts" -}}
<!-- use vendored copy to avoid cross site restrictions. See https://github.com/apache/parquet-site/pull/160 -->
<script src='{{ "vendor/docsearch/docsearch-3.8.2.min.js" | relURL }}'
integrity="sha512-lsD+XVzdBI6ZquXc8gqbw0/bgrfIsMJwY/8xvmvbN+U3gZSeG7BXQoCq4zv/yCmntR2GLHtgB+bD4ESPsKIbIA=="></script>
<script type="text/javascript">
const containers = ['#docsearch-0', '#docsearch-1'];
for (let c of containers) {
docsearch({
container: c,
appId: {{ .appId | default "R2IYF7ETH7" }},
apiKey: {{ .apiKey | default "599cec31baffa4868cae4e79f180729b" }},
indexName: {{ .indexName | default "docsearch" }},
});
}
</script>
{{ end -}}
Loading