Editing Template:TruthSocial/doc

{{template documentation}}
{{hatnote|This is the documentation for {{tl|TruthSocial}}. For the template code, see {{tl|TruthSocial}}.}}

== Purpose ==
Formats an embedded card for a post on [[Truth Social]], mirroring {{tl|Tweet}} but without Twitter-specific logic. It supports inline or block layouts, language tagging, optional translation, and a citation to the original post.

== Dependencies ==
* {{tl|Quote box}}
* {{tl|Formatting error}}
* {{tl|langx}} (or equivalent)
* [[Module:String]] (via <code>{{#invoke:String|replace}}</code>)

== Parameters ==
All parameters are unnamed unless stated.

; Required
* <code>name</code> – Display name of the author.
* <code>username</code> – Handle without the <code>@</code>.
* <code>text</code> – Post content. Basic wikitext allowed.
* <code>date</code> – Publication date. Must be DMY (<code>1 Jan 1970</code>) or MDY (<code>Jan 1, 1970</code>).
* <code>ID</code> / <code>id</code> – Numeric post ID. Required unless <code>reference</code>/<code>ref</code> supplied.

; Recommended
* <code>ref-name</code> – Named reference key (e.g., <code>Truth_username_ID</code>).

; Optional appearance
* <code>block</code> – Set to any non-empty value to use wide block layout (default width 500px).
* <code>width</code> – Override width. Default 500px when block, 220px when inline.
* <code>left</code> – Align left when inline. Default is right for inline; ignored for block.
* <code>style</code> – Extra CSS appended to the quote box.
* <code>image</code> – Filename of an avatar image to show left of the name (28×28px round).

; Optional context
* <code>replyto</code> – Username being replied to (without <code>@</code>).
* <code>lang</code> / <code>language</code> – BCP-47 code for the post text (e.g., <code>es</code>, <code>zh-Hans</code>).
* <code>translation</code> – A translated version shown under a rule.

; Citation control
* <code>reference</code> / <code>ref</code> – Raw <code><nowiki><ref>...</ref></nowiki></code> override. If omitted, a reference is auto-generated with {{tl|cite web}}.
* <code>cite-id</code> – Value for the <code>ref=</code> field inside the auto-generated citation.
* <code>archive-url</code>, <code>archive-date</code>, <code>url-status</code> – Passed through to {{tl|cite web}}.
* <code>nocategory</code> – Forwarded to {{tl|Formatting error}} to suppress categorization of formatting errors.

== Behavior ==
* **Logo:** A 18px logo is shown using a hotlinked SVG: <code>https://truthsocial.com//instance/images/truth-logo.svg</code>.
* **Date format enforcement:** If <code>date</code> is not in DMY or MDY, the template emits a formatting error message.
* **Reference requirement:** Either <code>ID</code>/<code>id</code> or <code>reference</code>/<code>ref</code> must be provided. Otherwise a formatting error is shown.
* **Auto citation:** If <code>ID</code> present and no custom <code>reference</code> provided, a named reference is generated:
  * <code>url</code>: <code>https://truthsocial.com/@&#123;&#123;username&#125;&#125;/posts/&#123;&#123;ID&#125;&#125;</code>
  * <code>title</code>: <code>text</code> collapsed to single spaces
  * <code>website</code>: “Truth Social”
  * <code>date</code>: <code>date</code>
  * <code>author</code>: <code>name</code>
  * Archive fields passed through if set.
* **Language:** If <code>lang</code> or <code>language</code> is set, the body is wrapped with {{tl|langx}}.

== Examples ==

=== Basic block usage ===
<pre>
{{TruthSocial
| name = Donald J. Trump
| username = realDonaldTrump
| text = Example Truth Social post text here.
| date = Jan 1, 2024
| ID = 123456789012345678
| ref-name = Truth_123456789012345678
| block = yes
}}
</pre>

=== Inline card, custom width ===
<pre>
{{TruthSocial
| name = Jane Doe
| username = janedoe
| text = Short update.
| date = 1 Jan 2025
| ID = 9876543210
| width = 260px
}}
</pre>

=== With avatar and reply context ===
<pre>
{{TruthSocial
| name = Jane Doe
| username = janedoe
| text = I disagree with that point.
| date = Feb 2, 2025
| ID = 1357911
| image = Jane_Doe_2024.jpg
| replyto = johndoe
| block = true
}}
</pre>

=== Language and translation ===
<pre>
{{TruthSocial
| name = María Pérez
| username = maria
| text = Este es un ejemplo.
| date = Mar 3, 2025
| ID = 24680
| lang = es
| translation = This is an example.
}}
</pre>

=== Custom reference (no ID) ===
<pre>
{{TruthSocial
| name = Jane Doe
| username = janedoe
| text = Off-platform mirror link.
| date = Apr 4, 2025
| reference = <ref>{{cite web|url=https://example.org|title=Mirror|website=Example|date=Apr 4, 2025}}</ref>
}}
</pre>

== Common errors ==
* **Missing name/username/text** → emits {{tl|Formatting error}} with guidance.
* **Missing date** or wrong format → emits a date-format {{tl|Formatting error}}.
* **Missing reference/ID** → emits a {{tl|Formatting error}} instructing to provide <code>reference</code> or <code>ID</code>.

== See also ==
* {{tl|Tweet}} – Twitter/X version with Snowflake date decoding.
* {{tl|Quote box}}

== TemplateData ==
<templatedata>
{
  "description": "Embed a formatted Truth Social post with optional translation and auto-generated citation.",
  "params": {
    "name": {
      "label": "Name",
      "description": "Display name of the author.",
      "type": "string",
      "required": true
    },
    "username": {
      "label": "Username",
      "description": "Truth Social handle without @.",
      "type": "string",
      "required": true
    },
    "text": {
      "label": "Text",
      "description": "Post content.",
      "type": "string",
      "required": true
    },
    "date": {
      "label": "Date",
      "description": "Publication date (DMY or MDY).",
      "type": "string",
      "required": true,
      "example": "Jan 1, 2024"
    },
    "ID": {
      "label": "Post ID",
      "description": "Numeric post ID (required unless a custom reference is supplied).",
      "type": "number",
      "required": false,
      "aliases": ["id"]
    },
    "ref-name": {
      "label": "Reference name",
      "description": "Name for the generated reference.",
      "type": "string",
      "required": false
    },
    "reference": {
      "label": "Custom reference",
      "description": "Override the generated citation with a custom <ref>…</ref>.",
      "type": "string",
      "required": false,
      "aliases": ["ref"]
    },
    "cite-id": {
      "label": "Cite ref id",
      "description": "Value passed to the ref= field of cite web.",
      "type": "string",
      "required": false
    },
    "image": {
      "label": "Avatar image",
      "description": "Local file name to show as a circular 28px avatar.",
      "type": "string",
      "required": false
    },
    "replyto": {
      "label": "Replying to",
      "description": "Username being replied to, without @.",
      "type": "string",
      "required": false
    },
    "lang": {
      "label": "Language",
      "description": "BCP-47 language code for the text.",
      "type": "string",
      "required": false,
      "aliases": ["language"]
    },
    "translation": {
      "label": "Translation",
      "description": "Translated text shown beneath the post.",
      "type": "string",
      "required": false
    },
    "block": {
      "label": "Block layout",
      "description": "Non-empty to enable wide block layout.",
      "type": "string",
      "required": false
    },
    "width": {
      "label": "Width",
      "description": "Overrides default width (500px block, 220px inline).",
      "type": "string",
      "required": false,
      "example": "480px"
    },
    "left": {
      "label": "Left align",
      "description": "When inline, align left instead of right.",
      "type": "string",
      "required": false
    },
    "style": {
      "label": "Extra styles",
      "description": "Additional CSS applied to the quote box.",
      "type": "string",
      "required": false
    },
    "archive-url": {
      "label": "Archive URL",
      "description": "Archive link passed to cite web.",
      "type": "string",
      "required": false
    },
    "archive-date": {
      "label": "Archive date",
      "description": "Archive date passed to cite web.",
      "type": "string",
      "required": false
    },
    "url-status": {
      "label": "URL status",
      "description": "URL status for cite web (e.g., 'live', 'dead').",
      "type": "string",
      "required": false
    },
    "nocategory": {
      "label": "No category",
      "description": "If set, suppresses error categories from Formatting error.",
      "type": "string",
      "required": false
    }
  }
}
</templatedata>

[[Category:Template documentation]]