Skip to content

[Documentation] docs/ddg.md: the header and Variables tables use inline HTML, which Google Docs now shows as raw text #397

Closed
pulsingSignal/stellar-engine
#1

Description

@JohnHales

Description of Documentation Need

Since 2026-10-05, Google Drive and Docs open Markdown files natively (Workspace Updates). An uploaded .md now stays an .md file and opens in Markdown mode, where, per Google's help page, "Web formatting (.HTML) turns into plain text". Until then, Drive converted an uploaded .md into a Google Doc. There is no admin or user setting to restore the old behavior.

Many operators fill in the DDG in Google Docs; the guide asks for a copy before the Variables table is filled in (line 34, "Please make a copy of this deployment guide before filling out the variable section below"). docs/ddg.md builds both of its tables with inline HTML. Line numbers are from main @ 2267b973:

  • <strong> around every label: 23 tags, in the header table (lines 5–9) and the Variables table (lines 66–78)
  • <a href='…'> for two links: line 68 (Console Link) and line 70 (compliance regime)
  • a <br/> in the Customer ID description (line 71)

GitHub renders these, so the file looks right in the repo. In Google Docs every row of the Variables table reads <strong>Billing Account</strong>, <strong>Prefix</strong> and so on. That happens both in Markdown mode and in the Google Doc that File > Save as Google Docs makes from it. PR #386's current head (93db8b7e) still carries all of them.

Target Audience

Operators and partners who work through the DDG in Google Docs, which is where the Variables table is filled in.

Proposed Location

docs/ddg.md: the header table (lines 5–9) and the Variables table (lines 66–78). No other file is involved.

Content Outline / Draft

Plain Markdown for the same formatting:

  1. <strong>X</strong> → **X** (23 places).
  2. Line 68: <a href='https://console.cloud.google.com/billing'>Console Link</a> → [Console Link](https://console.cloud.google.com/billing).
  3. Line 70: <a href='https://assuredworkloads.googleapis.com/$discovery/rest?version=v1'>compliance regime</a> → [compliance regime](https://assuredworkloads.googleapis.com/$discovery/rest?version=v1).
  4. Line 71: <br/> → a space. A table cell cannot hold a Markdown line break, and the sentence reads the same without it.

Optionally, a docs check such as grep -nE '</?(strong|a|br)\b' docs/*.md would keep inline HTML out of the guides.

Compliance Context (if applicable)

None. This is formatting only; no value, control or step changes.

Activity

  1. added
    DocumentationImprovements or additions to documentation
    Priority - MediumStandard features and non-blocking bugs; important for the current milestone but not urgent
    Level of Effort - LowQuick, well-defined tasks with no unknowns; takes a few hours up to one day to complete
    on Nov 3, 2026
  2. added
    Priority - LowMinor polish, typo fixes, or technical debt; nice to have; pick up when time permits
    and removed
    Priority - MediumStandard features and non-blocking bugs; important for the current milestone but not urgent
    on Nov 5, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    DocumentationImprovements or additions to documentationLevel of Effort - LowQuick, well-defined tasks with no unknowns; takes a few hours up to one day to completePriority - LowMinor polish, typo fixes, or technical debt; nice to have; pick up when time permits

    Type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions