+
+
+
{{ $page->t('Installation and integration requirements') }}
+
{{ $page->t('LibreSign is an app for a compatible Nextcloud server, not an independent standalone signing server. API integrations use an authorized Nextcloud account and its installation-specific permissions. Depending on configuration, external recipients can sign through invitations without a Nextcloud account.') }}
+
{{ $page->t('External applications can keep their own interface and workflows while their backend requests signatures and retrieves signed documents only with appropriate authorization. Consult the documentation for your installed LibreSign version.') }}
+
{{ $page->t('Read the API Integration Guide') }}
+
·
+
{{ $page->t('Official Documentation') }}
+
+
@include('_partials.home.card-grid-section', [
'sectionId' => 'it-pillars',
'sectionClass' => 'ud-it-pillars ud-page-section',
@@ -71,8 +81,8 @@
'subtitle' => $page->t('Discover the technical pillars that give your team freedom to innovate with confidence, visibility, and governance.'),
'items' => $itPillarItems,
'sectionActions' => [[
- 'href' => 'https://docs.libresign.coop/developer_manual/api/',
- 'label' => $page->t('Access API Documentation'),
+ 'href' => 'https://docs.libresign.coop/',
+ 'label' => $page->t('Choose Your Version for API Documentation'),
'class' => 'btn ud-btn-solid-brand',
'target' => '_blank',
]],
@@ -94,8 +104,8 @@
'class' => 'btn ud-btn-solid-warm',
],
[
- 'href' => 'https://docs.libresign.coop/admin_manual/',
- 'label' => $page->t('Read the Admin Documentation'),
+ 'href' => 'https://docs.libresign.coop/',
+ 'label' => $page->t('Choose Your Version for Admin Documentation'),
'class' => 'btn ud-btn-ghost',
'target' => '_blank',
],
diff --git a/tests/js/technical-discovery.test.mjs b/tests/js/technical-discovery.test.mjs
new file mode 100644
index 00000000..3975eee6
--- /dev/null
+++ b/tests/js/technical-discovery.test.mjs
@@ -0,0 +1,54 @@
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import test from 'node:test';
+
+const read = (name) => readFileSync(new URL('../../source/' + name, import.meta.url), 'utf8');
+const header = read('_layouts/header.blade.php');
+const home = read('index.blade.php');
+const features = read('features.blade.php');
+const technical = read('tecnical-details.blade.php');
+const faq = read('faq.blade.php');
+const guide = read('_posts/api-documentation.md');
+const layout = read('_layouts/main.blade.php');
+
+test('all primary discovery paths link to the original API guide and version chooser', () => {
+ for (const [name, source] of [['header', header], ['home', home], ['technical', technical], ['FAQ', faq]]) {
+ assert.match(source, /posts\/libresign-api-guide/, name + ' lacks a link to the existing guide');
+ }
+ for (const [name, source] of [['header', header], ['technical', technical], ['FAQ', faq]]) {
+ assert.match(source, /https:\/\/docs\.libresign\.coop\//, name + ' lacks official documentation');
+ }
+ assert.match(features, /category'\s*=>\s*'featured'/);
+ assert.match(header, /headerLocaleUrl\('features'\)/);
+ assert.match(faq, /foreach\(\$page->frequentlyQuestions/);
+});
+
+test('technical explanation distinguishes Nextcloud prerequisites, signers and authorized API access', () => {
+ assert.match(technical, /compatible Nextcloud server/);
+ assert.match(technical, /not an independent standalone signing server/);
+ assert.match(technical, /authorized Nextcloud account/);
+ assert.match(technical, /without a Nextcloud account/);
+ assert.match(technical, /retrieves signed documents only with appropriate authorization/);
+ assert.match(technical, /installed LibreSign version/);
+});
+
+test('existing guide identity, multilingual SEO and structured data are preserved', () => {
+ assert.match(guide, /^title: LibreSign API Guide$/m);
+ assert.match(guide, /^author: Vitor Mattos$/m);
+ assert.match(guide, /^date: 2024-10-10$/m);
+ assert.ok(layout.includes('rel="canonical" href="{{ $canonicalUrl }}"'));
+ assert.match(layout, /\$absoluteSeoUrl\(translate_url\(\$page, \$localeCode\)\)/);
+ assert.ok(layout.includes('property="og:url" content="{{ $canonicalUrl }}"'));
+ assert.ok(layout.includes('name="twitter:url" content="{{ $canonicalUrl }}"'));
+ assert.match(layout, /hreflang/);
+ assert.match(layout, /structured-data/);
+ assert.doesNotMatch(technical, /docs\.libresign\.coop\/(?:developer_manual|admin_manual)\//);
+});
+
+test('new interface strings use the Weblate extraction helper and not direct catalog edits', () => {
+ for (const source of [header, home, technical, faq]) {
+ assert.doesNotMatch(source, /lang\/en\/main\.json/);
+ }
+ assert.match(technical, /\$page->t\('Installation and integration requirements'\)/);
+ assert.match(faq, /\$page->t\('For installation, access permissions/);
+});
From 8b29ce96eb4876a54cb0f4a1a9629c8c8ce2a076 Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Sat, 14 Nov 2026 20:22:55 +0000
Subject: [PATCH 2/2] fix(site): resolve technical discovery review findings
Normalize social image URLs, improve link visibility and card spacing,
and validate the rendered HTML during preview builds.
Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
.github/workflows/preview.yml | 3 +
package.json | 3 +-
source/_assets/scss/_card.scss | 3 +
source/_layouts/main.blade.php | 4 +-
source/faq.blade.php | 9 ++-
source/tecnical-details.blade.php | 7 ++-
.../js/rendered-technical-discovery.smoke.mjs | 58 +++++++++++++++++++
tests/js/technical-discovery.test.mjs | 44 ++++----------
8 files changed, 86 insertions(+), 45 deletions(-)
create mode 100644 tests/js/rendered-technical-discovery.smoke.mjs
diff --git a/.github/workflows/preview.yml b/.github/workflows/preview.yml
index dc8fbdc0..2e7cb498 100644
--- a/.github/workflows/preview.yml
+++ b/.github/workflows/preview.yml
@@ -46,6 +46,9 @@ jobs:
WC_CONSUMER_SECRET: ${{ secrets.WC_CONSUMER_SECRET }}
run: composer prod
+ - name: Verify rendered SEO metadata and technical links
+ run: npm run test:html
+
- name: Upload fork preview artifact
if: github.event.pull_request.head.repo.full_name != github.repository
uses: actions/upload-artifact@v4
diff --git a/package.json b/package.json
index 8e107c60..41f0e0c4 100644
--- a/package.json
+++ b/package.json
@@ -6,7 +6,8 @@
"build-assets": "NODE_ENV=local vite build",
"staging": "NODE_ENV=staging vite build",
"prod": "NODE_ENV=production vite build",
- "test:js": "node --test tests/js/*.test.mjs"
+ "test:js": "node --test tests/js/*.test.mjs",
+ "test:html": "node --test tests/js/*.smoke.mjs"
},
"devDependencies": {
"@tighten/jigsaw-vite-plugin": "^2.0.0",
diff --git a/source/_assets/scss/_card.scss b/source/_assets/scss/_card.scss
index c5d5b3fa..32a2c88d 100644
--- a/source/_assets/scss/_card.scss
+++ b/source/_assets/scss/_card.scss
@@ -113,6 +113,9 @@
}
.ud-card__actions {
+ display: flex;
+ flex-direction: column;
+ gap: 12px;
padding-top: 16px;
width: 100%;
diff --git a/source/_layouts/main.blade.php b/source/_layouts/main.blade.php
index c3b987a3..ffef4bb8 100644
--- a/source/_layouts/main.blade.php
+++ b/source/_layouts/main.blade.php
@@ -36,7 +36,7 @@
-
+
@@ -45,7 +45,7 @@
-
+
diff --git a/source/faq.blade.php b/source/faq.blade.php
index 939d5036..79ee9196 100644
--- a/source/faq.blade.php
+++ b/source/faq.blade.php
@@ -65,11 +65,10 @@ class="ud-faq-btn collapsed"
@include('_partials.home.card-grid-section', [
diff --git a/tests/js/rendered-technical-discovery.smoke.mjs b/tests/js/rendered-technical-discovery.smoke.mjs
new file mode 100644
index 00000000..6bbcd00f
--- /dev/null
+++ b/tests/js/rendered-technical-discovery.smoke.mjs
@@ -0,0 +1,58 @@
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import test from 'node:test';
+
+const buildRoot = new URL('../../build_production/', import.meta.url);
+const html = (path) => readFileSync(new URL(path, buildRoot), 'utf8');
+const tags = (page, name) => [...page.matchAll(new RegExp('<' + name + '\\b[^>]*>', 'gi'))].map((match) => match[0]);
+const attribute = (tag, name) => tag?.match(new RegExp('\\b' + name + '="([^"]*)"', 'i'))?.[1] ?? null;
+const namedTag = (page, element, attributeName, value) =>
+ tags(page, element).find((tag) => attribute(tag, attributeName) === value);
+
+test('generated pages have absolute canonical, hreflang and social image URLs', () => {
+ for (const path of [
+ 'index.html',
+ 'faq/index.html',
+ 'tecnical-details/index.html',
+ 'pt-BR/tecnical-details/index.html',
+ ]) {
+ const page = html(path);
+ const canonical = attribute(namedTag(page, 'link', 'rel', 'canonical'), 'href');
+ assert.match(canonical ?? '', /^https:\/\//, path + ': canonical must be absolute');
+ const canonicalOrigin = new URL(canonical).origin;
+
+ const alternates = tags(page, 'link').filter((tag) =>
+ attribute(tag, 'rel') === 'alternate' && attribute(tag, 'hreflang'));
+ assert.ok(alternates.length > 0, path + ': missing hreflang');
+ for (const alternate of alternates) {
+ assert.match(attribute(alternate, 'href') ?? '', /^https:\/\//, path + ': hreflang must be absolute');
+ }
+
+ for (const [name, key] of [['og:image', 'property'], ['twitter:image', 'name']]) {
+ const image = attribute(namedTag(page, 'meta', key, name), 'content');
+ assert.match(image ?? '', /^https:\/\//, path + ': ' + name + ' must be absolute');
+ assert.equal(new URL(image).origin, canonicalOrigin, path + ': ' + name + ' must use the site origin');
+ assert.match(new URL(image).pathname, /\/assets\/images\/logo\/logo-libresign-large\.png$/);
+ }
+ }
+});
+
+test('rendered technical guide links are styled and external docs open safely', () => {
+ for (const path of ['index.html', 'faq/index.html', 'tecnical-details/index.html']) {
+ const anchors = tags(html(path), 'a');
+ assert.ok(anchors.some((tag) =>
+ /posts\/libresign-api-guide/.test(attribute(tag, 'href') ?? '') &&
+ /\bud-btn-solid-brand\b/.test(attribute(tag, 'class') ?? '')
+ ), path + ': missing styled API guide action');
+ }
+
+ for (const path of ['faq/index.html', 'tecnical-details/index.html']) {
+ const anchors = tags(html(path), 'a');
+ assert.ok(anchors.some((tag) =>
+ attribute(tag, 'href') === 'https://docs.libresign.coop/' &&
+ /\bud-btn-outline-brand\b/.test(attribute(tag, 'class') ?? '') &&
+ attribute(tag, 'target') === '_blank' &&
+ attribute(tag, 'rel') === 'noopener noreferrer'
+ ), path + ': missing safely opened documentation action');
+ }
+});
diff --git a/tests/js/technical-discovery.test.mjs b/tests/js/technical-discovery.test.mjs
index 3975eee6..85b1117a 100644
--- a/tests/js/technical-discovery.test.mjs
+++ b/tests/js/technical-discovery.test.mjs
@@ -5,50 +5,26 @@ import test from 'node:test';
const read = (name) => readFileSync(new URL('../../source/' + name, import.meta.url), 'utf8');
const header = read('_layouts/header.blade.php');
const home = read('index.blade.php');
-const features = read('features.blade.php');
const technical = read('tecnical-details.blade.php');
const faq = read('faq.blade.php');
-const guide = read('_posts/api-documentation.md');
const layout = read('_layouts/main.blade.php');
-test('all primary discovery paths link to the original API guide and version chooser', () => {
+test('primary discovery paths reference the API guide and documentation chooser', () => {
for (const [name, source] of [['header', header], ['home', home], ['technical', technical], ['FAQ', faq]]) {
- assert.match(source, /posts\/libresign-api-guide/, name + ' lacks a link to the existing guide');
+ assert.match(source, /posts\/libresign-api-guide/, name + ' lacks an API guide link');
}
for (const [name, source] of [['header', header], ['technical', technical], ['FAQ', faq]]) {
- assert.match(source, /https:\/\/docs\.libresign\.coop\//, name + ' lacks official documentation');
+ assert.match(source, /https:\/\/docs\.libresign\.coop\//, name + ' lacks a documentation chooser');
}
- assert.match(features, /category'\s*=>\s*'featured'/);
- assert.match(header, /headerLocaleUrl\('features'\)/);
- assert.match(faq, /foreach\(\$page->frequentlyQuestions/);
+ assert.doesNotMatch(technical, /docs\.libresign\.coop\/(?:developer_manual|admin_manual)\//);
});
-test('technical explanation distinguishes Nextcloud prerequisites, signers and authorized API access', () => {
- assert.match(technical, /compatible Nextcloud server/);
- assert.match(technical, /not an independent standalone signing server/);
- assert.match(technical, /authorized Nextcloud account/);
- assert.match(technical, /without a Nextcloud account/);
- assert.match(technical, /retrieves signed documents only with appropriate authorization/);
- assert.match(technical, /installed LibreSign version/);
+test('social image URLs use the origin resolver even with production baseUrl="/"', () => {
+ assert.match(layout, /property="og:image" content="\{\{\s*\$absoluteSeoUrl\(/);
+ assert.match(layout, /name="twitter:image" content="\{\{\s*\$absoluteSeoUrl\(/);
});
-test('existing guide identity, multilingual SEO and structured data are preserved', () => {
- assert.match(guide, /^title: LibreSign API Guide$/m);
- assert.match(guide, /^author: Vitor Mattos$/m);
- assert.match(guide, /^date: 2024-10-10$/m);
- assert.ok(layout.includes('rel="canonical" href="{{ $canonicalUrl }}"'));
- assert.match(layout, /\$absoluteSeoUrl\(translate_url\(\$page, \$localeCode\)\)/);
- assert.ok(layout.includes('property="og:url" content="{{ $canonicalUrl }}"'));
- assert.ok(layout.includes('name="twitter:url" content="{{ $canonicalUrl }}"'));
- assert.match(layout, /hreflang/);
- assert.match(layout, /structured-data/);
- assert.doesNotMatch(technical, /docs\.libresign\.coop\/(?:developer_manual|admin_manual)\//);
-});
-
-test('new interface strings use the Weblate extraction helper and not direct catalog edits', () => {
- for (const source of [header, home, technical, faq]) {
- assert.doesNotMatch(source, /lang\/en\/main\.json/);
- }
- assert.match(technical, /\$page->t\('Installation and integration requirements'\)/);
- assert.match(faq, /\$page->t\('For installation, access permissions/);
+test('new technical links use the Weblate extraction helper', () => {
+ assert.match(technical, /id="it-requirements-heading">\{\{\s*\$page->t\(/);
+ assert.match(faq, /https:\/\/docs\.libresign\.coop\/"[^>]*>\{\{\s*\$page->t\(/);
});