diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index df7c18b79..37ed77117 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -28,12 +28,13 @@ There are several active versions of the documentation. Each version derives fro Each version has a branch in the repository named accordingly: -- 11 -- 12 -- 13 +- 11 (EOL) +- 12 (EOL) +- 13 - 14 - 15 - 16 +- 17 The source .md files are in the ``docs`` directory. @@ -140,14 +141,17 @@ mkdocs serve ``` 6. To build the PDF documentation, do the following: - - Install [mkdocs-with-pdf plugin](https://pypi.org/project/mkdocs-with-pdf/) + - Install [mkdocs-print-site-plugin](https://timvink.github.io/mkdocs-print-site-plugin/index.html) - Run the following command ```sh ENABLE_PDF_EXPORT=1 mkdocs build -f mkdocs-pdf.yml ``` -The PDF document is in the ``site/pdf`` folder. +This creates a single HTML page for the whole doc project. You can find the page at `site/print_page.html`. + +7. Open the `site/print_page.html` in your browser and save as PDF. Depending on the browser, you may need to select the Export to PDF, Print - Save as PDF or just Save and select PDF as the output format. + ## Repository structure @@ -161,13 +165,16 @@ The repository includes the following directories and files: - `_images` - Images, logos and favicons - `css` - Styles - `js` - Javascript files -- `_resource`: - - `templates`: + - `templates`: - ``styles.scss`` - Styling for PDF documents - - `theme`: + - `pdf_cover_page.tpl` - The PDF cover page template +- `_resource`: + - `overrides` - The directory with customized templates for HTML output - `main.html` - The layout template for hosting the documentation on Percona website - - overrides - The folder with the template customization for Netlify builds +- `_resourcepdf`: + - `overrides` - The directory with customized layout templates for PDF - `.github`: - `workflows`: - `main.yml` - The workflow configuration for building documentation with a GitHub action. (The documentation is built with `mike` tool to a dedicated `netlify` branch) - `site` - This is where the output HTML files are put after the build +- `snippets` - The folder with pieces of documentation used in multiple places diff --git a/_resourcepdf/overrides/404.html b/_resourcepdf/overrides/404.html new file mode 100644 index 000000000..3d3717301 --- /dev/null +++ b/_resourcepdf/overrides/404.html @@ -0,0 +1,9 @@ +{#- + This file was automatically generated - do not edit +-#} +{% extends "main.html" %} +{% block content %} +

404 - Not found

+

+We can't find the page you are looking for. Try using the Search or return to homepage .

+{% endblock %} diff --git a/_resourcepdf/overrides/main.html b/_resourcepdf/overrides/main.html new file mode 100644 index 000000000..545cd7c41 --- /dev/null +++ b/_resourcepdf/overrides/main.html @@ -0,0 +1,69 @@ +{# +MkDocs template for builds with Material theme to customize docs layout +by adding marketing-requested elements +#} + +{# Import the theme's layout. #} +{% extends "base.html" %} + + + {% block site_nav %} + {% if nav %} + {% if page.meta and page.meta.hide %} + {% set hidden = "hidden" if "navigation" in page.meta.hide %} + {% endif %} + + {% endif %} + {% if "toc.integrate" not in features %} + {% if page.meta and page.meta.hide %} + {% set hidden = "hidden" if "toc" in page.meta.hide %} + {% endif %} + + {% endif %} + {% endblock %} + + {% block content%} + + {{ super() }} + + + + {% endblock %} \ No newline at end of file diff --git a/_resourcepdf/overrides/partials/banner.html b/_resourcepdf/overrides/partials/banner.html new file mode 100644 index 000000000..830718b90 --- /dev/null +++ b/_resourcepdf/overrides/partials/banner.html @@ -0,0 +1,9 @@ +
+

+

For help, click the link below to get free database assistance or contact our experts for personalized support.

+ +
+ + Get help from Percona +
+
\ No newline at end of file diff --git a/_resourcepdf/overrides/partials/copyright.html b/_resourcepdf/overrides/partials/copyright.html new file mode 100644 index 000000000..dd0f101fa --- /dev/null +++ b/_resourcepdf/overrides/partials/copyright.html @@ -0,0 +1,14 @@ +{#- + This file was automatically generated - do not edit +-#} +
+
+ Percona LLC and/or its affiliates, © {{ build_date_utc.strftime('%Y') }} — Cookie Preferences +
+ {% if not config.extra.generator == false %} + Made with + + Material for MkDocs + + {% endif %} +
\ No newline at end of file diff --git a/_resourcepdf/overrides/partials/header.html b/_resourcepdf/overrides/partials/header.html new file mode 100644 index 000000000..2d0d6e740 --- /dev/null +++ b/_resourcepdf/overrides/partials/header.html @@ -0,0 +1,135 @@ + + + +{% set class = "md-header" %} +{% if "navigation.tabs.sticky" in features %} + {% set class = class ~ " md-header--shadow md-header--lifted" %} +{% elif "navigation.tabs" not in features %} + {% set class = class ~ " md-header--shadow" %} +{% endif %} + + +
+ + +
+
+ + + + + + + + + + Percona Software for PostgreSQL Documentation + +
+
+ + + + + {% if "navigation.tabs.sticky" in features %} + {% if "navigation.tabs" in features %} + {% include "partials/tabs.html" %} + {% endif %} + {% endif %} +
\ No newline at end of file diff --git a/docs/templates/pdf_cover_page.tpl b/docs/templates/pdf_cover_page.tpl new file mode 100644 index 000000000..b5ab6ed46 --- /dev/null +++ b/docs/templates/pdf_cover_page.tpl @@ -0,0 +1,12 @@ + +{{ config.extra.added_key }} +

+ +

+

Distribution for PostgreSQL

+{% if config.site_description %} +

{{ config.site_description }}

+{% endif %} +

16.8 (February 27, 2025)

+ + diff --git a/mkdocs-base.yml b/mkdocs-base.yml index a08921644..16157af2a 100644 --- a/mkdocs-base.yml +++ b/mkdocs-base.yml @@ -125,24 +125,29 @@ plugins: macros: include_yaml: - 'variables.yml' # Use in markdown as '{{ VAR }}' -# exclude: # Don't process these files -# glob: -# - file.md - with-pdf: # https://github.com/orzih/mkdocs-with-pdf - output_path: '_pdf/PerconaDistributionPostgreSQL-16.pdf' - cover_title: 'Distribution for PostgreSQL Documentation' - - cover_subtitle: 16.8 (February 27, 2025) - author: 'Percona Technical Documentation Team' - cover_logo: docs/_images/Percona_Logo_Color.png - debug_html: false - custom_template_path: _resource/templates - enabled_if_env: ENABLE_PDF_EXPORT mike: version_selector: true css_dir: css javascript_dir: js canonical_version: null + print-site: + add_to_navigation: false + print_page_title: 'Percona Distribution for PostgreSQL documentation' + add_print_site_banner: false + # Table of contents + add_table_of_contents: true + toc_title: 'Table of Contents' + toc_depth: 2 + # Content-related + add_full_urls: false + enumerate_headings: false + enumerate_headings_depth: 1 + enumerate_figures: true + add_cover_page: true + cover_page_template: "docs/templates/pdf_cover_page.tpl" + path_to_pdf: "" + include_css: true + enabled: true extra: version: diff --git a/mkdocs-pdf.yml b/mkdocs-pdf.yml deleted file mode 100644 index c6ffae69c..000000000 --- a/mkdocs-pdf.yml +++ /dev/null @@ -1,17 +0,0 @@ -# MkDocs configuration for PDF builds -# Usage: ENABLE_PDF_EXPORT=1 mkdocs build -f mkdocs-pdf.yml - -INHERIT: mkdocs-base.yml - -copyright: Percona LLC, © 2024 - -extra_css: - - https://unicons.iconscout.com/release/v3.0.3/css/line.css - - https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.4.0/css/font-awesome.min.css - - css/percona.css - - css/extra.css - - css/osano.css - -markdown_extensions: - pymdownx.tabbed: {} - admonition: {} diff --git a/mkdocs.yml b/mkdocs.yml index a91b409f6..1c08d4616 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -6,7 +6,7 @@ site_url: "https://docs.percona.com/postgresql/" theme: name: material - custom_dir: _resource/overrides/ + custom_dir: _resourcepdf/overrides/ extra: analytics: @@ -28,6 +28,63 @@ extra: feedback form. -#markdown_extensions: -# - pymdownx.tabbed: -# alternate_style: true +nav: + - 'Home': 'index.md' + - get-help.md + - Get started: + - Quickstart guide: installing.md + - 1. Install: + - Via apt: apt.md + - Via yum: yum.md + - From tarballs: tarball.md + - Run in Docker: docker.md + - enable-extensions.md + - repo-overview.md + - 2. Connect to PostgreSQL: connect.md + - 3. Manipulate data in PostgreSQL: crud.md + - 4. What's next: whats-next.md + - Extensions: + - 'Extensions': extensions.md + - contrib.md + - Percona-authored extensions: percona-ext.md + - third-party.md + - Solutions: + - Overview: solutions.md + - High availability: + - 'High availability': 'solutions/high-availability.md' + - 'Deploying on Debian or Ubuntu': 'solutions/ha-setup-apt.md' + - 'Deploying on RHEL or derivatives': 'solutions/ha-setup-yum.md' + - solutions/pgbackrest.md + - solutions/ha-test.md + - Backup and disaster recovery: + - 'Overview': 'solutions/backup-recovery.md' + - solutions/dr-pgbackrest-setup.md + - Spatial data handling: + - Overview: solutions/postgis.md + - Deployment: solutions/postgis-deploy.md + - Query spatial data: solutions/postgis-testing.md + - Upgrade spatial database: solutions/postgis-upgrade.md + - LDAP authentication: + - ldap.md + - Upgrade: + - "Major upgrade": major-upgrade.md + - minor-upgrade.md + - migration.md + - Troubleshooting guide: troubleshooting.md + - Uninstall: uninstalling.md + - Release Notes: + - "Release notes index": "release-notes.md" + - release-notes-v16.8.md + - release-notes-v16.6.md + - release-notes-v16.4.md + - release-notes-v16.3.md + - release-notes-v16.2.md + - release-notes-v16.1.upd.md + - release-notes-v16.1.md + - release-notes-v16.0.upd.md + - release-notes-v16.0.md + - Reference: + - Telemetry: telemetry.md + - Licensing: licensing.md + - Trademark policy: trademark-policy.md + diff --git a/requirements.txt b/requirements.txt index 031d9e13a..ce82d86ff 100644 --- a/requirements.txt +++ b/requirements.txt @@ -15,4 +15,5 @@ mkdocs-htmlproofer-plugin mkdocs-meta-descriptions-plugin mike Pillow > 10.1.0 -mkdocs-open-in-new-tab \ No newline at end of file +mkdocs-open-in-new-tab +mkdocs-print-site-plugin \ No newline at end of file