This is an automated email from the ASF dual-hosted git repository.
jamesbognar pushed a commit to branch docs
in repository https://gitbox.apache.org/repos/asf/juneau.git
The following commit(s) were added to refs/heads/docs by this push:
new 50cf2433d1 Document Markdown view rendering; rename
juneau-secret-keychain to juneau-secret-macos-keychain
50cf2433d1 is described below
commit 50cf2433d1b4b5401d476a7586d63eb04a5f26b0
Author: James Bognar <[email protected]>
AuthorDate: Wed Aug 19 13:12:24 2026 -0400
Document Markdown view rendering; rename juneau-secret-keychain to
juneau-secret-macos-keychain
- Add new topic page 10.65.MarkdownViewRendering, wired into sidebars.ts.
- Rename juneau-secret-keychain -> juneau-secret-macos-keychain across
artifact-paths.json, the 10.0.0 release notes, JuneauCommonsSettings docs,
and about.md to match the module's new name.
---
artifact-paths.json | 5 +-
pages/release-notes/10.0.0.md | 4 +-
pages/topics/02.06.JuneauCommonsSettings.md | 4 +-
pages/topics/10.65.MarkdownViewRendering.md | 108 ++++++++++++++++++++++++++++
sidebars.ts | 5 ++
src/pages/about.md | 4 +-
6 files changed, 123 insertions(+), 7 deletions(-)
diff --git a/artifact-paths.json b/artifact-paths.json
index b4de8e0bca..f66361c2e9 100644
--- a/artifact-paths.json
+++ b/artifact-paths.json
@@ -59,6 +59,9 @@
"juneau-rest-server-auth-oauth": "juneau-rest/juneau-rest-server-auth-oauth",
"juneau-rest-server-auth-oidc-rp":
"juneau-rest/juneau-rest-server-auth-oidc-rp",
"juneau-rest-server-auth-saml": "juneau-rest/juneau-rest-server-auth-saml",
+ "juneau-rest-server-console-ui": "juneau-rest/juneau-rest-server-console-ui",
+ "juneau-rest-server-console-ui-freemarker":
"juneau-rest/juneau-rest-server-console-ui-freemarker",
+ "juneau-rest-server-console-ui-freemarker-datatables":
"juneau-rest/juneau-rest-server-console-ui-freemarker-datatables",
"juneau-rest-server-datatables": "juneau-rest/juneau-rest-server-datatables",
"juneau-rest-server-management-logging":
"juneau-rest/juneau-rest-server-management-logging",
"juneau-rest-server-mcp": "juneau-rest/juneau-rest-server-mcp",
@@ -76,7 +79,7 @@
"juneau-rest-server-view-thymeleaf":
"juneau-rest/juneau-rest-server-view-thymeleaf",
"juneau-sc": "juneau-sc",
"juneau-sc-server": "juneau-sc/juneau-sc-server",
- "juneau-secret-keychain": "juneau-secret-keychain",
+ "juneau-secret-macos-keychain": "juneau-secret-macos-keychain",
"juneau-shaded": "juneau-shaded",
"juneau-shaded-all": "juneau-shaded/juneau-shaded-all",
"juneau-shaded-core": "juneau-shaded/juneau-shaded-core",
diff --git a/pages/release-notes/10.0.0.md b/pages/release-notes/10.0.0.md
index f44772365f..5706c81163 100644
--- a/pages/release-notes/10.0.0.md
+++ b/pages/release-notes/10.0.0.md
@@ -143,7 +143,7 @@ See the new [`@ConfigProperties` Annotation
Basics](/docs/topics/ConfigPropertie
[RestContext](/docs/topics/RestContext#restcontextproperties--env-driven-defaults-via-configproperties-1000)
topic
page for the pilot.
-### juneau-commons / juneau-secret-keychain
+### juneau-commons / juneau-secret-macos-keychain
### `SecretStore` SPI — the secure, mutable sibling of `PropertySource`
@@ -161,7 +161,7 @@ storing and retrieving secrets by key — `store` / `find` /
`exists` / `delete`
- **Opt-in Settings bridge** — `SecretStorePropertySource` exposes a chosen
store as a `PropertySource` only where a
consumer deliberately wires it, and implements the `SensitivePropertySource`
marker so dump/log/`toString()` paths
redact bridged values. Secrets stay out of the general config/`$P{...}`/SVL
namespace by default.
-- **New opt-in module `juneau-secret-keychain`** — a `KeychainSecretStore`
backed by the macOS `security` keychain
+- **New opt-in module `juneau-secret-macos-keychain`** — a
`KeychainSecretStore` backed by the macOS `security` keychain
CLI, honoring a `ReplayCache`-style `FailMode` (fail-open/fail-closed) for
backend-unavailable behavior. It lives
outside `juneau-commons` because it shells out to an OS process.
diff --git a/pages/topics/02.06.JuneauCommonsSettings.md
b/pages/topics/02.06.JuneauCommonsSettings.md
index b0e5e7945b..fc01dcebeb 100644
--- a/pages/topics/02.06.JuneauCommonsSettings.md
+++ b/pages/topics/02.06.JuneauCommonsSettings.md
@@ -273,8 +273,8 @@ a marker that dump/log/`toString()` paths honor to redact
bridged values.
### OS keychain-backed store
-The opt-in `juneau-secret-keychain` module ships a
-<java-class><a
href="/site/apidocs/org/apache/juneau/secret/keychain/KeychainSecretStore.html"
target="_blank">KeychainSecretStore</a></java-class>
+The opt-in `juneau-secret-macos-keychain` module ships a
+<java-class><a
href="/site/apidocs/org/apache/juneau/secret/macos/keychain/KeychainSecretStore.html"
target="_blank">KeychainSecretStore</a></java-class>
backed by the macOS `security` keychain CLI. Because it shells out to an
external OS process, it lives outside
`juneau-commons` (which holds the line on zero-runtime-deps /
no-OS-integration). It honors a
<java-class><a
href="/site/apidocs/org/apache/juneau/commons/secret/FailMode.html"
target="_blank">FailMode</a></java-class>
diff --git a/pages/topics/10.65.MarkdownViewRendering.md
b/pages/topics/10.65.MarkdownViewRendering.md
new file mode 100644
index 0000000000..805e62296d
--- /dev/null
+++ b/pages/topics/10.65.MarkdownViewRendering.md
@@ -0,0 +1,108 @@
+---
+title: "Markdown View Rendering (juneau-rest-server-views-markdown)"
+slug: MarkdownViewRendering
+---
+
+`juneau-rest-server-views` renders data tables and
`juneau-rest-server-console-ui` renders chrome — neither
+has any concept of a rendered *document*. The optional
`juneau-rest-server-views-markdown` module fills that gap:
+hand it a markdown string, get back an HTML fragment, the same way a `ViewDef`
turns a list of beans into a themed
+table.
+
+Because it is a separate, opt-in module, consumers that don't need markdown
pay nothing — no markdown parser is
+dragged into `juneau-rest-server` or the views toolkit by default.
+
+```xml
+<dependency>
+ <groupId>org.apache.juneau</groupId>
+ <artifactId>juneau-rest-server-views-markdown</artifactId>
+ <version>${juneau.version}</version>
+</dependency>
+```
+
+## The `MarkdownRenderer` SPI
+
+The module's single extension point is the library-neutral
+<a
href="/site/apidocs/org/apache/juneau/rest/server/views/markdown/MarkdownRenderer.html"
target="_blank">MarkdownRenderer</a>
+interface — one method, `String toHtml(String markdown)`, so any parser can
sit behind it:
+
+```java
+MarkdownRenderer renderer = MarkdownRenderer.resolve();
+String html = renderer.toHtml("# Runbook\n\nStep one.");
+```
+
+`MarkdownRenderer.resolve()` selects the active renderer via the standard
`java.util.ServiceLoader` mechanism:
+
+- If a consumer registers their own provider (a
`META-INF/services/org.apache.juneau.rest.server.views.markdown.MarkdownRenderer`
+ file naming their implementation class), that provider wins.
+- Otherwise the built-in commonmark-java default is used.
+
+The default is intentionally **not** registered as a service, so a single
consumer-supplied provider is always
+unambiguous.
+
+## The default: commonmark-java with GFM tables
+
+The shipped default,
+<a
href="/site/apidocs/org/apache/juneau/rest/server/views/markdown/CommonmarkMarkdownRenderer.html"
target="_blank">CommonmarkMarkdownRenderer</a>,
+wraps [commonmark-java](https://github.com/commonmark/commonmark-java)
(BSD-2-Clause) with the
+[GFM tables extension](https://github.github.com/gfm/#tables-extension-)
enabled out of the box. GFM tables are on
+by default because real documents (runbooks, onboarding guides) routinely use
pipe tables, and core CommonMark
+renders them as paragraphs of literal pipes.
+
+```java
+CommonmarkMarkdownRenderer renderer = new CommonmarkMarkdownRenderer();
+
+// A GFM pipe table renders as a real <table>, not literal pipes.
+String html = renderer.toHtml("""
+ | Name | Role |
+ | --- | --- |
+ | Alice | Admin |
+ """);
+```
+
+commonmark-java's parser and renderer are immutable and thread-safe once
built, so a single renderer instance is
+safe to share across threads and reuse for every render.
+
+## Swapping the parser
+
+To use a different parser (or a differently-configured commonmark instance),
implement `MarkdownRenderer` and
+register it as a service:
+
+```java
+public class MyMarkdownRenderer implements MarkdownRenderer {
+ @Override
+ public String toHtml(String markdown) {
+ // ... your parser here ...
+ }
+}
+```
+
+`META-INF/services/org.apache.juneau.rest.server.views.markdown.MarkdownRenderer`:
+
+```
+com.example.MyMarkdownRenderer
+```
+
+`MarkdownRenderer.resolve()` will now return your implementation instead of
the commonmark default.
+
+## Styling the output
+
+The rendered HTML is meant to be dropped inside a `.jc-prose` container so it
inherits the console's prose
+typography (heading scale, list rhythm, `pre`/`code`, blockquote, and a
static-table rule):
+
+```html
+<div class="jc-prose">
+ <!-- MarkdownRenderer.resolve().toHtml(...) output here -->
+</div>
+```
+
+See [Admin-Console Chrome](/docs/topics/AdminConsoleChrome) for the
`.jc-prose` contract.
+
+## Panel wiring
+
+Wiring rendered markdown into a `Tab`/`Subtab` panel's content property is a
deferred follow-on integration point,
+not part of this module — this module ships the renderer SPI and the
commonmark-java default only.
+
+## See Also
+
+- [MarkdownRenderer
Javadoc](/site/apidocs/org/apache/juneau/rest/server/views/markdown/package-summary.html)
+- [commonmark-java](https://github.com/commonmark/commonmark-java)
diff --git a/sidebars.ts b/sidebars.ts
index adf2179954..8f813ef85c 100644
--- a/sidebars.ts
+++ b/sidebars.ts
@@ -1777,6 +1777,11 @@ const sidebars: SidebarsConfig = {
id:
'topics/10.64.AdminConsoleChrome',
label: '10.64.
Admin-Console Chrome (juneau-rest-server-console-ui)',
},
+ {
+ type: 'doc',
+ id:
'topics/10.65.MarkdownViewRendering',
+ label: '10.65. Markdown
View Rendering (juneau-rest-server-views-markdown)',
+ },
],
link: {
type: 'doc',
diff --git a/src/pages/about.md b/src/pages/about.md
index c40478a0db..8273d77786 100644
--- a/src/pages/about.md
+++ b/src/pages/about.md
@@ -91,8 +91,8 @@ The Juneau ecosystem consists of the following parts. A few
rows are **grouped f
| [juneau-microservice-tomcat](/docs/topics/JuneauMicroserviceTomcat) |
Tomcat-embedded microservice launcher. |
| **juneau-sc** | |
| [juneau-sc-server](/docs/topics/ScServerOverview) | Centralized
configuration server exposing juneau-config files over REST. |
-| **juneau-secret-keychain** | |
-|
[juneau-secret-keychain](/docs/topics/JuneauCommonsSettings#os-keychain-backed-store)
| Opt-in module providing a macOS `security`-CLI-backed `KeychainSecretStore`
implementation of the `SecretStore` SPI. |
+| **juneau-secret-macos-keychain** | |
+|
[juneau-secret-macos-keychain](/docs/topics/JuneauCommonsSettings#os-keychain-backed-store)
| Opt-in module providing a macOS `security`-CLI-backed `KeychainSecretStore`
implementation of the `SecretStore` SPI. |
| **juneau-shaded** | |
| [juneau-shaded-core](/docs/topics/JuneauShadedCore) | Shaded uber-jar of the
juneau-core modules for zero-conflict dependency management. |
| [juneau-shaded-rest-client](/docs/topics/JuneauShadedRestClient) | Shaded
uber-jar of juneau-rest-client and its dependencies. |
