You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@iceberg.apache.org by bl...@apache.org on 2022/03/15 02:38:23 UTC
[iceberg-docs] branch main updated: Add anchor tags and table of contents (#63)
This is an automated email from the ASF dual-hosted git repository.
blue pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/iceberg-docs.git
The following commit(s) were added to refs/heads/main by this push:
new b69dc3f Add anchor tags and table of contents (#63)
b69dc3f is described below
commit b69dc3f3ff752fce71ea94d5431aac27fcfaf64a
Author: Samuel Redai <43...@users.noreply.github.com>
AuthorDate: Mon Mar 14 22:28:09 2022 -0400
Add anchor tags and table of contents (#63)
---
landing-page/content/common/spec.md | 17 +++++++------
landing-page/layouts/_default/single.html | 19 ++++++++++++--
landing-page/layouts/partials/head.html | 1 -
landing-page/layouts/partials/header.html | 2 +-
landing-page/layouts/partials/toc.html | 7 ++++++
landing-page/static/css/landing-page.css | 41 +++++++++++++++++++++++++++++++
landing-page/static/css/markdown.css | 2 +-
7 files changed, 76 insertions(+), 13 deletions(-)
diff --git a/landing-page/content/common/spec.md b/landing-page/content/common/spec.md
index 11a2564..913f6c4 100644
--- a/landing-page/content/common/spec.md
+++ b/landing-page/content/common/spec.md
@@ -1,5 +1,6 @@
---
url: spec
+toc: true
aliases:
- "spec"
---
@@ -30,13 +31,13 @@ Versions 1 and 2 of the Iceberg spec are complete and adopted by the community.
The format version number is incremented when new features are added that will break forward-compatibility---that is, when older readers would not read newer table features correctly. Tables may continue to be written with an older version of the spec to ensure compatibility by not using features that are not yet implemented by processing engines.
-#### Version 1: Analytic Data Tables
+### Version 1: Analytic Data Tables
Version 1 of the Iceberg spec defines how to manage large analytic tables using immutable file formats: Parquet, Avro, and ORC.
All version 1 data and metadata files are valid after upgrading a table to version 2. [Appendix E](spec/#version-2) documents how to default version 2 fields when reading version 1 metadata.
-#### Version 2: Row-level Deletes
+### Version 2: Row-level Deletes
Version 2 of the Iceberg spec adds row-level updates and deletes for analytic tables with immutable files.
@@ -67,7 +68,7 @@ Data files in snapshots are tracked by one or more manifest files that contain a
The manifests that make up a snapshot are stored in a manifest list file. Each manifest list stores metadata about manifests, including partition stats and data file counts. These stats are used to avoid reading manifests that are not required for an operation.
-#### Optimistic Concurrency
+### Optimistic Concurrency
An atomic swap of one table metadata file for another provides the basis for serializable isolation. Readers use the snapshot that was current when they load the table metadata and are not affected by changes until they refresh and pick up a new metadata location.
@@ -77,7 +78,7 @@ If the snapshot on which an update is based is no longer current, the writer mus
The conditions required by a write to successfully commit determines the isolation level. Writers can select what to validate and can make different isolation guarantees.
-#### Sequence Numbers
+### Sequence Numbers
The relative age of data and delete files relies on a sequence number that is assigned to every successful commit. When a snapshot is created for a commit, it is optimistically assigned the next sequence number, and it is written into the snapshot's metadata. If the commit fails and must be retried, the sequence number is reassigned and written into new snapshot metadata.
@@ -86,7 +87,7 @@ All manifests, data files, and delete files created for a snapshot inherit the s
Inheriting the sequence number from manifest metadata allows writing a new manifest once and reusing it in commit retries. To change a sequence number for a retry, only the manifest list must be rewritten -- which would be rewritten anyway with the latest set of manifests.
-#### Row-level Deletes
+### Row-level Deletes
Row-level deletes are stored in delete files.
@@ -98,7 +99,7 @@ There are two ways to encode a row-level delete:
Like data files, delete files are tracked by partition. In general, a delete file must be applied to older data files with the same partition; see [Scan Planning](spec/#scan-planning) for details. Column metrics can be used to determine whether a delete file's rows overlap the contents of a data file or a scan range.
-#### File System Operations
+### File System Operations
Iceberg only requires that file systems support the following operations:
@@ -115,7 +116,7 @@ Tables do not require rename, except for tables that use atomic rename to implem
## Specification
-#### Terms
+### Terms
* **Schema** -- Names and types of fields in a table.
* **Partition spec** -- A definition of how partition values are derived from data fields.
@@ -125,7 +126,7 @@ Tables do not require rename, except for tables that use atomic rename to implem
* **Data file** -- A file that contains rows of a table.
* **Delete file** -- A file that encodes rows of a table that are deleted by position or data values.
-#### Writer requirements
+### Writer requirements
Some tables in this spec have columns that specify requirements for v1 and v2 tables. These requirements are intended for writers when adding metadata files to a table with the given version.
diff --git a/landing-page/layouts/_default/single.html b/landing-page/layouts/_default/single.html
index 1c0f42d..72652ba 100644
--- a/landing-page/layouts/_default/single.html
+++ b/landing-page/layouts/_default/single.html
@@ -2,11 +2,26 @@
<head>
<link href="{{ .Site.BaseURL }}/css/markdown.css" rel="stylesheet">
<link href="{{ .Site.BaseURL }}/css/katex.min.css" rel="stylesheet">
+ <script>
+ // This automatically adds an anchor tag for every h1, h2, h3, and h4 element on the page
+ function addAnchor(element) {
+ element.insertAdjacentHTML('beforeend', `<a href="#${element.id}" class="anchortag" ariaLabel="Anchor"> 🔗 </a>` )
+ }
+ document.addEventListener('DOMContentLoaded', function () {
+ var headers = document.querySelectorAll('h1[id], h2[id], h3[id], h4[id]')
+ if (headers) {
+ headers.forEach(addAnchor)
+ }
+ });
+ </script>
</head>
{{ partial "header.html" . }}
<body dir="{{ .Site.Language.LanguageDirection | default " ltr" }}">
- <div class="markdown-body">
- {{- .Content -}}
+ <div class="grid-container">
+ {{ partial "toc.html" . }}
+ <div class="markdown-body">
+ {{- .Content -}}
+ </div>
</div>
</body>
diff --git a/landing-page/layouts/partials/head.html b/landing-page/layouts/partials/head.html
index 1cfdd2a..7225818 100644
--- a/landing-page/layouts/partials/head.html
+++ b/landing-page/layouts/partials/head.html
@@ -7,7 +7,6 @@
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="description" content="">
<meta name="author" content="">
- <base href="{{ .Site.BaseURL }}">
<title>{{ .Title }}</title>
diff --git a/landing-page/layouts/partials/header.html b/landing-page/layouts/partials/header.html
index 85b3871..24bbd7e 100644
--- a/landing-page/layouts/partials/header.html
+++ b/landing-page/layouts/partials/header.html
@@ -9,7 +9,7 @@
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
- <a class="page-scroll navbar-brand" href="#intro"><img class="top-navbar-logo" src="{{ .Site.BaseURL }}/img/iceberg-logo-icon.png"/> {{ .Site.Title }}</a>
+ <a class="page-scroll navbar-brand" href="{{ .Site.BaseURL }}"><img class="top-navbar-logo" src="{{ .Site.BaseURL }}/img/iceberg-logo-icon.png"/> {{ .Site.Title }}</a>
</div>
<!-- Collect the nav links, forms, and other content for toggling -->
diff --git a/landing-page/layouts/partials/toc.html b/landing-page/layouts/partials/toc.html
new file mode 100644
index 0000000..0a84d0d
--- /dev/null
+++ b/landing-page/layouts/partials/toc.html
@@ -0,0 +1,7 @@
+{{ if (.Params.toc) }}
+<div id="toc" class="markdown-body">
+ <div id="full">
+ {{.TableOfContents}}
+ </div>
+</div>
+{{ end }}
\ No newline at end of file
diff --git a/landing-page/static/css/landing-page.css b/landing-page/static/css/landing-page.css
index f35b3b1..e966cd4 100644
--- a/landing-page/static/css/landing-page.css
+++ b/landing-page/static/css/landing-page.css
@@ -9,6 +9,8 @@ html {
width: 100%;
height: 100%;
font-size: 20px;
+ scroll-padding-top: 3rem;
+ scroll-behavior: smooth;
}
body,
@@ -225,3 +227,42 @@ a.page-scroll {
.termynal-container {
padding-top: 3rem;
}
+
+/* Anchor tags for headers */
+.anchortag { font-size: 80%; visibility: hidden;}
+
+h1:hover a { visibility: visible}
+h2:hover a { visibility: visible}
+h3:hover a { visibility: visible}
+h4:hover a { visibility: visible}
+
+/* Fixed table of contents */
+.grid-container {
+ display: grid;
+ grid-template-columns: 5fr 1fr;
+ grid-gap: 1rem;
+}
+
+
+#toc {
+ position: fixed;
+ right: 0;
+ top: 0;
+ background-color:#FFF;
+ display: block;
+ flex: 0 0 20rem;
+ font-size: 0.6rem;
+ width: 20rem;
+ min-width: 0;
+ padding: 2rem;
+ margin-top: 2rem;
+ list-style-type: none;
+}
+
+#toc ul {
+ list-style: none;
+}
+
+@media screen and (min-width: 401px) and (max-width: 1280px) {
+ #toc { display: none; } /* Hide the TOC if the page is less than 1280px */
+ }
\ No newline at end of file
diff --git a/landing-page/static/css/markdown.css b/landing-page/static/css/markdown.css
index 9a2f0ee..9e7dc0e 100644
--- a/landing-page/static/css/markdown.css
+++ b/landing-page/static/css/markdown.css
@@ -226,7 +226,7 @@ body {
}
.markdown-body a:hover {
- text-decoration: underline
+ text-decoration: none
}
.markdown-body hr::before {