Website Markdown for SMEs: URL, synchronization, and testing

Website Markdown refers to a machine-readable version of a page that represents the relevant content of a public HTML page in a simplified text structure under a stable, uniquely identifiable URL. The Markdown version complements the HTML page but does not replace it. Both versions should originate from the same content source, have the same publication status, and be reviewed together.

For a South Tyrolean SME, the main benefit lies in a reliable, machine-readable website : content can be exported more easily, processed further, and read by various technical systems. However, this does not guarantee inclusion or preferential treatment by search engines and AI providers.

Before you develop Markdown pages, three points should be clarified:

• Use: Key content is made available in a reduced, easily extractable structure.
• Requirement: HTML and Markdown are derived from a common, binding database.
• Border: Forms, bookings, interactive elements and visual user guidance remain the responsibility of the HTML page or suitable interfaces.

Implementing Website Markdown: The Complete Process

A robust implementation doesn't begin with the file format, but with the content model. If services, contacts, locations, sources, and language versions are maintained inconsistently, a Markdown export will only create another inconsistent version.

I recommend a seven-step process for website Markdown:

1. Modeling content: Define mandatory fields for title, introduction, main content, achievements, people, locations, sources, images, and update date.
2. Establish a single source of truth: Identify a central content source from which all public representations will be generated. Our 30-Day Start Plan for a Single Source of Truth This organizational aspect is explored in greater depth.
3. Generate HTML and Markdown: The HTML page includes navigation, design, and interactive features. The Markdown version contains the relevant editorial content without a menu, cookie text, footer repetitions, or design aids.
4. Uniquely assign URLs: Each public HTML page receives exactly one defined Markdown URL per language.
5. Linking language versions: Language code, translated URL, internal links and metadata must match the actual language.
6. Publish simultaneously: One change invalidates both versions. HTML and Markdown are regenerated in the same publishing process.
7. Automated check: Status codes, headings, links, language, sources, timeliness and content parity are checked before and after publication.

A Markdown version only reduces maintenance effort if it is created as an additional output of the same authoritative content source and not as a separate editorial channel.

The content source is more important than the output format.

A single source of truth is not a single large text file. It is the authoritative source for structured facts and editorial content. This includes, for example, company name, service descriptions, opening hours, contact information, responsible persons, locations, and source references.

In practice, I separate three levels:

• Facts and entities: Companies, people, services, places, contact details and relationships.
• Editorial content: Introductions, explanations, examples, FAQs and sources.
• Output rules: Specifications for how HTML, Markdown, and structured data are generated from the content.

This separation prevents the same phone number, service description, or source information from having to be manually changed in multiple places.

It also establishes clear responsibilities: The editorial team is responsible for content, language, and sources. The development team is responsible for the generator, URLs, and HTTP status codes. SEO is responsible for information architecture and indexing decisions. Data protection is responsible for excluding sensitive data.

Which URL convention makes sense for website Markdown?

A good URL convention is stable, readable, testable, and linguistically unambiguous. For many SME projects, I recommend a dedicated Markdown URL that directly links to the HTML page.

A simple model looks like this:

• HTML: https://example.com/de/leistungen/webdesign/
• Markdown: https://example.com/de/leistungen/webdesign.md
• Italian HTML: https://example.com/it/servizi/web-design/
• Italian Markdown: https://example.com/it/servizi/web-design.md

The file extension .md The relationship is quickly recognizable for people, protocols, and tests. A separate path like this one... /markdown/de/leistungen/webdesign/ This is also possible, but it lengthens the URLs and changes the basis for relative links. The crucial factor is not the chosen form, but its consistent application.

Alternative: Content Negotiation

HTTP can deliver multiple representations of the same resource via Content Negotiation . RFC 9110 describes how the Accept header transmits preferred media types and weights them using q-values. The server identifies the selected representation with Content-Type. If no acceptable version is available, the HTTP status code 406 Not Acceptable can be used.

Technically, the same URL could return HTML or Markdown depending on the Accept header. This standardized model brings additional requirements:

• Caches must correctly account for the selection, typically via Vary: Accept.
• The desired representation is more difficult to directly access and check in the browser.
• Errors in proxies or caching layers are harder to trace.
• The Markdown version cannot be easily shared as a standalone link target.

For most SMEs, I therefore prefer a dedicated Markdown URL. Content negotiation makes sense if development, infrastructure, and monitoring are already designed for alternative representations.

Set redirects and status codes

Error cases are also part of the URL convention:

• 200 OK: The Markdown version is available and up-to-date.
• 301 or 308: The HTML page has been permanently moved; the associated Markdown URL is consistently redirected.
• 404 Not Found: No public version exists for the requested URL.
• 410 Gone: The content was deliberately and permanently removed.
• 406 Not Acceptable: Can be used in content negotiation when no suitable representation is available.

An untranslated Italian Markdown page should not display German content under an Italian URL. Until the translation is approved, the language version should not be linked and should return a correct 404 status when accessed directly.

This is how a Markdown version should be structured.

Website Markdown should reflect the main content in a structured way and not copy all the visible text of the HTML page. Navigation, cookie notices, recurring footer text, and user instructions do not usually belong in the Markdown version.

A compact sample version might look like this:

---
source_url: https://example.com/de/leistungen/webdesign/
language: de
updated_at: YYYY-MM-DD
---

# Webdesign für Südtiroler KMU

Kurze, konkrete Zusammenfassung der Leistung und ihres Nutzens.

## Was wir umsetzen

- Website-Strategie und Informationsarchitektur
- UX- und UI-Konzept
- technische Entwicklung
- mehrsprachige Inhalte
- Qualitätssicherung vor der Veröffentlichung

## Für wen die Leistung geeignet ist

Beschreibung der passenden Unternehmen, Anforderungen und Grenzen.

## Häufige Fragen

### Wie lange bleibt der Inhalt aktuell?

HTML und Markdown werden gemeinsam aus derselben Inhaltsquelle erzeugt.

## Quellen

- [Bezeichnung der Quelle](https://example.org/quelle)

## Kontakt

[Unternehmen kontaktieren](https://example.com/de/kontakt/)

The following rules apply to the structure:

• Use exactly one H1 as a page title.
• Arrange sections logically using H2 and H3, without skipping levels.
• Use descriptive link text instead of "learn more" or bare URLs.
• Use lists for services, features, processes, and comparisons.
• Add a meaningful image description to each picture.
• Support external statements with verifiable source information.
• Copy the source code as a clearly defined block of code.
• Use optional metadata only according to a documented, project-specific convention.

Convert tables into lists or sections

Tables are possible in Markdown, but they quickly become cluttered on small screens and with automatic extraction. I recommend converting tabular HTML content into lists or clearly named sections.

A performance comparison can have a separate section for each offer, outlining criteria such as suitability , included features , requirements , and limitations . The information content remains intact, while mobile and AI readability become more robust.

Canonical attribution without blanket SEO promises

The HTML page remains the primary web representation for both people and search engines. The Markdown version should clearly indicate its origin, for example via a field. source_url and a visible link to the HTML page.

For a Markdown resource delivered as a non-HTML document, it is technically possible to set an HTTP link header:

Link: <https://example.com/de/leistungen/webdesign/>; rel="canonical"

Google Search Central documents the canonical HTTP header for supported non-HTML documents such as PDF and Word files. The canonical directive is a signal indicating the preferred, representative URL and is not a binding instruction. The documentation does not explicitly mention Markdown as a separate example.

For canonical mapping, this means:

• The Markdown version links to the corresponding HTML page.
• The assignment is done per language and not generally to a German main page.
• Canonical does not replace a clean URL structure or a conscious indexing decision.
• Canonical does not prove that AI systems retrieve or prefer the Markdown version.

Properly representing multilingualism in South Tyrol

Multilingualism must be incorporated into the content model itself, as a combination of independent language versions. For many South Tyrolean SMEs, this applies to German and Italian, and potentially other languages ​​as well.

A clean implementation is required:

• a stable URL for each language and output format
• a consistent language code such as de, it or en,
• translated page titles, headings and link texts,
• Internal links to the appropriate language version,
• the same business entities and relationships across all languages,
• a documented status for drafting, translation and approval.

The entity "Company" remains the same in all languages. Descriptions, URLs, and labels may differ. A German service page should not link to Italian content in its Markdown version if a German landing page is available.

Relative links require special attention. If the Markdown URL changes the directory depth, a previously working link may lead nowhere. Therefore, the generator should resolve internal links based on the language and output them as correct absolute or tested relative URLs.

Automate updates and content parity

A common operational error is an outdated Markdown version. Therefore, keeping it up-to-date is an ongoing governance task and not a one-time export.

A reliable publishing process follows this pattern:

1. The editorial team is changing the content in the central source.
2. The system saves version, language, and update time.
3. HTML, Markdown, and any structured data will be regenerated.
4. Caches for all affected versions will be invalidated.
5. Automated tests check status, structure, links, and content parity.
6. All versions will only be published after successful review.
7. Errors are logged along with the affected URL, language, and version.

Content parity does not mean that HTML and Markdown must be identical character for character. However, relevant statements, numbers, performance characteristics, sources, and contact information must match. Navigation, visual components, and form logic may be omitted from Markdown.

Technical and editorial quality assurance

Before being submitted, each Markdown page should undergo a technical and content review.

Technical Inspection

• HTTP status code: Does the intended URL return a 200 error instead of an error page with an apparent 200 status?
• Content type and character encoding: Is the format correctly labeled and is UTF-8 delivered cleanly?
• Heading sequence: Is there exactly one H1 and one comprehensible H2/H3 structure?
• Link targets: Do internal, external, and language-related links work?
• Canonical assignment: Does the Markdown version link to the corresponding HTML page in the same language?
• Monitoring: Monitoring: Are errors and outdated versions logged?

Content review

• Sources: Are the sources complete, up-to-date, and correctly matched to the respective statements?
• Language assignment: Do the URL, language code, and actual language match?
• Update time: Does the current version match the published HTML page?
• Content parity: Do the facts, figures, achievements, people, and contact details match?
• Confidentiality: Does the publication contain only information that is permitted to be public?

For regular inventory checks, you can also use our 60-minute check for machine-readable websites.

Website Markdown does not replace HTML or Schema.org.

Markdown forms a text-oriented access layer. Semantic HTML remains relevant for usability, accessibility, navigation, forms, and search engines. Structured data fulfills a separate, independent function.

Structured data using Schema.org describes entities and relationships in a standardized vocabulary: A company has a location, offers a service, or employs a person. Markdown, on the other hand, provides readable content with a simplified document structure.

The three levels complement each other:

• HTML: Presentation, interaction, navigation and semantic page structure.
• Markdown: Reduced, text-oriented representation of the relevant content.
• Schema.org data: formalized entities, properties, and relationships.

Transactional functions such as reservations, orders, price calculations, or protected areas still require HTML applications or documented APIs. A Markdown page can explain and link to such functions, but it cannot replace them.

Are Markdown pages preferred by AI systems?

A Markdown version can make content technically more accessible. However, this does not guarantee citation, recommendation, or a better ranking.

Google clarifies in its guide to generative search features that Google Search does not require any special Markdown or llms.txt files. Google can discover and index different file types, but it does not automatically prioritize Markdown. llms.txt is not used as a ranking or visibility signal.

An llms.txt file is a voluntary orientation file for systems that actually evaluate this convention. The existence of an llms.txt file or a Markdown output does not prove that a particular AI crawler is accessing it.

The practical value of website Markdown therefore lies in clear content, fewer contradictions, traceable sources, stable URLs, and controlled updates. These characteristics support people, internal systems, search engines, and suitable AI applications.

A practical example from working with SMEs

In an SME project, we found performance data in multiple versions: on the website, in a PDF, in presentations, and in internal text documents. Descriptions, scope of services, and contact persons were not consistent across all versions. An additional Markdown file would initially have increased the number of conflicting versions.

Therefore, we first clarified editorial responsibility and established a central content database. The HTML pages and simplified text versions were then created jointly from this. Changes to a service were approved once and subsequently regenerated in all planned editions.

The crucial step forward was clear responsibility: Who is allowed to change facts, who checks the language, who verifies sources, and who approves publication? This order was the prerequisite for reliable automation.

btlabs Core as a possible implementation model

One possible technical approach is a central, multilingual content repository from which different outputs are generated. With btlabs Core, Markdown output can be delivered from the same content repository as the website. The system is designed for multilingual maintenance and data sovereignty.

Even with such an architecture, technical provisioning does not guarantee discoverability or preferential processing by AI systems. Content, information architecture, correct language mapping, sources, technical accessibility, and ongoing quality assurance remain crucial.

A 30-day induction plan

Days 1 to 7: Pilot and Convention

• Select five to ten public pilot sites.
• Define relevant and excluded content.
• Define URL convention, language codes, and canonical mapping.
• Designate persons responsible for editorial content, development, SEO, and data protection.

Days 8 to 14: Develop generator

• Model titles, sections, lists, links, images, sources, and metadata.
• Generate HTML and Markdown from the same source.
• Transform tables into lists or outlined sections.
• Resolve internal links depending on language and output format.

Days 15 to 21: Set up automated tests

• Check the HTTP status code, content type, and character encoding.
• Validate headings, links, language code, and sources.
• Compare key facts between HTML and Markdown.
• Test redirects, remote pages, and missing translations.

Days 22 to 30: publish and monitor

• Publish only the pilot pages initially.
• Check server logs and error messages.
• Check if changes are applied to both versions.
• Document deviations and improve the generator.
• Only then should you roll out the system to other page types.

Questions and answers about the Markdown edition

Does every public website need a Markdown version?

No. Start with pages whose content is professionally relevant, permanently public, and text-based, such as services, locations, technical articles, and FAQs. Help pages without independent informational value do not automatically require a Markdown version.

What content should the Markdown page exclude?

Exclude navigation, cookie texts, recurring footer content, internal notices, and confidential data. Forms can be described and linked as contact options; the actual interaction remains on the HTML page.

How do I prevent outdated Markdown versions?

Generate HTML and Markdown in the same publishing process and invalidate both versions on any relevant change. Include a machine-readable update timestamp and automatic tests that report differing publication states.

Is an .md URL or Content Negotiation better?

For many SMEs, having their own .mdURLs are easier to test, link, and monitor in logs. Content Negotiation is standardized but requires careful cache configuration and more technical experience in day-to-day operations.

Can Markdown pages be indexed?

Search engines can crawl and index various publicly accessible file types in addition to HTML. Whether a specific Markdown page is indexed depends on factors such as accessibility, backlinks, indexing rules, and the decision of the individual search engine. A Markdown version does not guarantee indexing or improved visibility.

How are images and downloads handled?

Images are given a descriptive name and a stable public URL. Downloads are explained with file type, content, and purpose so that humans and technical systems can understand the link destination.

How are forms displayed in Markdown?

Markdown describes the purpose and required information of the form and then links to the interactive HTML page. Sensitive form data, hidden fields, and internal processing logic do not belong in the public Markdown version.

How do I deal with language variants that have not yet been translated?

Do not publish a German replacement version under an Italian or English URL. Omit the unavailable language version and provide a correct error status when accessing the site directly until translation and editorial approval are complete.

How often should the Markdown output be checked?

Automated basic checks should be run with every publication. Additionally, I recommend spot checks after major content changes, technical updates, and adjustments to URL or language structures.

Conclusion: Website Markdown is an additional access layer.

A robust website Markdown architecture is not made up of manually copied text files. It combines centralized content management with stable URLs, consistent language versions, traceable sources, and automated checks.

Build the common content source first, and only then the additional outputs. This creates a machine-readable page version that limits maintenance effort and avoids creating another conflicting content source.

After over 20 years in web development, branding, and digitalization, I regularly see this in SMEs: technology doesn't solve unclear responsibilities. Clearly defined responsibilities and a shared quality standard are essential for consistently operating website Markdown correctly.

Sources

1. RFC 9110: HTTP Semantics — rfc-editor.org (2022)
2. Google Search Central: Setting Canonical URLs — developers.google.com (2026)
3. Google Search Central: Optimization for generative search functions — developers.google.com (2026)