diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c87fac8be..b36079a02 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -30,12 +30,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 (EOL) - 14 - 15 - 16 +- 17 The source .md files are in the ``docs`` directory. @@ -146,14 +147,17 @@ The PDF document is in the ``site/pdf`` folder. ``` 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 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 @@ -167,13 +171,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 Material theme template customization for 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 `publish` 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..6f02aa976 --- /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..7e130f43f --- /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/docs/enable-extensions.md b/docs/enable-extensions.md index 57992b02f..096e87dae 100644 --- a/docs/enable-extensions.md +++ b/docs/enable-extensions.md @@ -136,8 +136,6 @@ After the installation, enable the following option in `postgresql.conf` configu wal_level = logical ``` -<<<<<<< HEAD -======= Start / restart the server to apply the changes. ## pgvector @@ -148,7 +146,6 @@ To get started, enable the extension for the database where you want to use it: CREATE EXTENSION vector; ``` ->>>>>>> 7845a94c... PG-1214 Documented install and enable pgvector steps ## Next steps [Connect to PostgreSQL :material-arrow-right:](connect.md){.md-button} \ 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..72a02963b --- /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 %} +

13.20 (March 6, 2025)

+ + diff --git a/mkdocs-base.yml b/mkdocs-base.yml index 428b4321f..2b864294e 100644 --- a/mkdocs-base.yml +++ b/mkdocs-base.yml @@ -138,31 +138,36 @@ 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-13.pdf' - cover_title: 'Distribution for PostgreSQL Documentation' - cover_subtitle: 13.20 (March 6, 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: provider: mike #homepage: # https://docs.percona.com - postgresrecommended: 16 + postgresrecommended: 13 nav: - 'Home': 'index.md' diff --git a/mkdocs-pdf.yml b/mkdocs-pdf.yml deleted file mode 100644 index 04fce8a68..000000000 --- a/mkdocs-pdf.yml +++ /dev/null @@ -1,10 +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, © 2025 - -markdown_extensions: - pymdownx.tabbed: {} - admonition: {} \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 5bc02a97f..182e28325 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -5,6 +5,9 @@ INHERIT: mkdocs-base.yml site_url: "https://docs.percona.com/postgresql/" +theme: + name: material + custom_dir: _resourcepdf/overrides/ extra: analytics: @@ -26,8 +29,4 @@ extra: feedback form. -#markdown_extensions: -# - pymdownx.tabbed: -# alternate_style: true - diff --git a/requirements.txt b/requirements.txt index 031d9e13a..cbcb20b8d 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