Maintaining the utPLSQL Website

The utPLSQL website is generated using MkDocs and material theme Mike is used for versioning of documentation see also this page

Announcements are published with the Material blog plugin.

• Create a new post file in the docs/announcements/posts directory, in the subfolder for the year (e.g. 2026/), with the file name of YYYY-MM-DD-Blog-Post-Name.md. This file will be a standard Markdown file which can be edited with any text editor.
• Start the file with front matter:

  ---
  title:  "utPLSQL v3.2.3 released"
  date:
    created: 2026-07-10
  categories:
    - "releases"
    - "utplsql-core"
  description: "Optional one-line summary shown on the home page card and in search results."
  pin: false
  ---

• Put <!-- more --> after the first paragraph - everything above it is shown as the excerpt on the Announcements page.
• Commit and push changes to the main branch.

The post URL is built from the title (announcements/<slugified-title>.html), not from the file name or folder, so posts can be moved between folders without breaking links. Relative links inside a post (e.g. to images in docs/assets) are relative to the post file, so they need adjusting when a post is moved.

There is no need to update mkdocs.yml or index.md - the post appears on the Announcements page and on the home page automatically.

The "Latest News" cards on the home page are generated by a custom MkDocs hook: hooks/latest_posts.py. The Material blog plugin has no built-in way to list posts on other pages, so the hook fills that gap.

How it works:

• On every build, the hook replaces the <!-- latest-posts --> placeholder in docs/index.md with Material grid cards for the most recent posts.

• Posts come from the blog plugin (config.plugins["material/blog"].blog.posts), in the same order as on the Announcements page: pinned posts first, then newest first. Draft posts are skipped.

• Each card shows an icon based on the post category, the title, the date and categories, a short summary and a "Read more" link. The whole card is clickable.

• The summary is, in order of preference:

  1. the description: from the post front matter,
  2. the first paragraph before the first list - e.g. an intro sentence written above ## What's Changed in the GitHub release notes,
  3. the list items of the release notes, joined with · and without author, PR and issue references (by @user in #123, Fixed in ..., resolves ...), e.g. Fix issue with UT_TAP_REPORTER on Oracle 23.26 · Fixed support for camelCase ... · +4 more.

  Headings, **Full Changelog**: ... lines, link-only lines (e.g. [Download ...](...)) and bare URLs are never used. The summary is trimmed to about 180 characters.

• Posts without a description: also get the generated summary as their <meta name="description">, used by search engines.

• Release announcements generated by the release pipeline need no changes - the summary is built from the release notes automatically.

Controlling what is shown:

• To keep a post on the home page, add pin: true to its front matter. Its card is shown first with the same pin badge as on the Announcements page, and the post also stays at the top of the Announcements page. Pinned posts count towards COUNT. Remove the flag when it should drop off.
• To control the card text, add a description: to the post front matter.
• The number of cards (COUNT), summary length (SUMMARY_LENGTH) and category icons (ICONS) are set at the top of hooks/latest_posts.py. Icons use the Material icon shortcode syntax.

Related configuration:

• hooks: in mkdocs.yml registers the hook.
• The attr_list, md_in_html and pymdownx.emoji Markdown extensions in mkdocs.yml are required for the cards and icons.
• The .latest-posts styles in docs/stylesheets/extra.css make the whole card clickable and style the date line and "Read more" link.

The hook is plain Python run by MkDocs itself - no extra package needs to be installed. Note that it relies on MkDocs hooks and on internals of the Material blog plugin, so it needs to be revisited when upgrading Material or migrating to Zensical.

Announcements are published as RSS and JSON feeds by the mkdocs-rss-plugin, configured under rss: in mkdocs.yml:

• feed_rss_created.xml - newest posts first (the one to subscribe to),
• feed_rss_updated.xml - most recently updated posts first,
• feed_json_created.json and feed_json_updated.json - the same as JSON Feed.

Only posts under docs/announcements/posts/ are included (match_path), up to 20 newest. Dates come from date.created / date.updated in the post front matter (git history is used when date.updated is missing), and categories become RSS categories. The item description is the post description: or the summary generated by hooks/latest_posts.py - the same text as on the home page card.

The feeds are linked from the home page, the Announcements page and the RSS icon in the footer, and Material adds <link rel="alternate" type="application/rss+xml"> to every page, so feed readers find them automatically.

If you want to generate and preview the website locally, you will need to have python and pip installed)

To install mkdocs required components, you need to execute the below commands from command line:

pip install mkdocs-material
pip install mkdocs-git-revision-date-localized-plugin
pip install mkdocs-include-markdown-plugin
pip install mkdocs-git-committers-plugin-2
pip install mkdocs-rss-plugin
pip install mike

Once installed you can use following commands from command line:

mkdocs serve - will stat a local server, so you can see the web page generated locally and tet real-time updates to documentation

The pages are automatically generated on every commit to the main branch. If however you would need to generate pages manually from your local copy, use the command: mkdocs gh-deploy. The generated web pages are hen visible at utplsql.org.

Individual project documentation pages are deployed separately from the main organization page. Each corresponding project repository needs to have its own gh-pages branch.

utPLSQL-framework repository uses mike to deploy documentation for specific project version.

Example commands to use are:

• mike deploy develop - to deploy documentation for develop branch
• mike deploy -p develop - to deploy and push documentation for develop branch
• mike deploy -p -u v3.1.12 latest - to deploy and push documentation for version v3.1.12 and update the latest alias to point to that version