254 lines
7.3 KiB
Plaintext
254 lines
7.3 KiB
Plaintext
---
|
||
title: Code Components
|
||
last_edited: '2025-07-30T02:30:04.636Z'
|
||
auto_generated: false
|
||
---
|
||
|
||
Several components have been implemented to help out with software documentation.
|
||
|
||
## Code Blocks
|
||
|
||
For multiline code samples, use triple backticks. You can also specify which language is used in the fenced code block for associated code highlighting.
|
||
|
||
```javascript
|
||
js function greet(name) {
|
||
return `Hello, ${name}!`
|
||
}
|
||
```
|
||
|
||
### Syntax Highlighting
|
||
|
||
TinaDocs uses [Shiki](https://shiki.style/) to power code block rendering, because of this you are able to also use [Shiki's Transformer Notation](https://shiki.style/guide/transformers) for special highlighting.
|
||
|
||
```javascript
|
||
console.log('This is a highlighted block') // [!code highlight]
|
||
|
||
It uses "[!code highlight]" in a comment after the code
|
||
```
|
||
|
||
### Diff Highlighting
|
||
|
||
```javascript
|
||
console.log('This is a negative diff') // [!code --]
|
||
console.log('This is a positive diff') // [!code ++]
|
||
|
||
It uses "[!code --]" or "[!code ++]" in a comment after the code
|
||
```
|
||
|
||
### Focused Highlighting
|
||
|
||
```javascript
|
||
console.log('Junk Code');
|
||
console.log('Focused Code'); // [!code focus]
|
||
console.log('More hidden code');
|
||
|
||
It uses "[!code focus]" in a comment after the code
|
||
```
|
||
|
||
## Tabbed Code Blocks
|
||
|
||
Tabbed code blocks let you present multiple language variants or configurations side-by-side—ideal for showing equivalent code in JavaScript, TypeScript, Bash, or specific queries and responses.
|
||
|
||
This improves readability and UX for polyglot dev environments.
|
||
|
||
<codeTabs
|
||
tabs={[
|
||
{
|
||
name: "cURL",
|
||
content: "curl<72>-<2D>X<EFBFBD>GET<45>https://jsonplaceholder.typicode.com/posts/1",
|
||
language: "shell"
|
||
},
|
||
{
|
||
name: "Response",
|
||
content:
|
||
'{\n<><6E>"userId":<3A>1,\n<><6E>"id":<3A>1,\n<><6E>"title":<3A>"sunt<6E>aut<75>facere<72>repellat<61>provident<6E>occaecati<74>excepturi<72>optio<69>reprehenderit",\n<><6E>"body":<3A>"quia<69>et<65>suscipit\\nsuscipit<69>recusandae<61>consequuntur<75>expedita<74>et<65>cum..."\n}',
|
||
language: "json"
|
||
}
|
||
]}
|
||
initialSelectedIndex={1}
|
||
/>
|
||
|
||
<codeTabs
|
||
tabs={[
|
||
{
|
||
name: "React",
|
||
content:
|
||
"import<72>React,<2C>{<7B>useState<74>}<7D>from<6F>'react';\n\nfunction<6F>Counter()<29>{\n<><6E>const<73>[count,<2C>setCount]<5D>=<3D>useState(0);\n\n<><6E>return<72>(\n<><6E><EFBFBD><EFBFBD><div>\n<><6E><EFBFBD><EFBFBD><EFBFBD><EFBFBD><p>Count:<3A>{count}</p>\n<><6E><EFBFBD><EFBFBD><EFBFBD><EFBFBD><button<6F>onClick={()<29>=><3E>setCount(count<6E>+<2B>1)}>Increment</button>\n<><6E><EFBFBD><EFBFBD></div>\n<><6E>);\n}\n\nexport<72>default<6C>Counter;",
|
||
language: "javascript"
|
||
},
|
||
{
|
||
name: "Vue",
|
||
content:
|
||
"<template>\n<><6E><div>\n<><6E><EFBFBD><EFBFBD><p>Count:<3A>{{<7B>count<6E>}}</p>\n<><6E><EFBFBD><EFBFBD><button<6F>@click=\"increment\">Increment</button>\n<><6E></div>\n</template<74>>\n\n<script<70>setup>\n<><6E>import<72>{ref}<7D>from<6F>'vue';\n\n<><6E>const<73>count<6E>=<3D>ref(0);\n<><6E>const<73>increment<6E>=<3D>()<29>=><3E>count.value++;\n</script>",
|
||
language: "javascript"
|
||
},
|
||
{
|
||
name: "Angular",
|
||
content:
|
||
"import<72>{<7B>Component<6E>}<7D>from<6F>'@angular/core';\n\n@Component({\n<><6E>selector:<3A>'app-counter',\n<><6E>template:<3A>`\n<><6E><EFBFBD><EFBFBD><div>\n<><6E><EFBFBD><EFBFBD><EFBFBD><EFBFBD><p>Count:<3A>{{<7B>count<6E>}}</p>\n<><6E><EFBFBD><EFBFBD><EFBFBD><EFBFBD><button<6F>(click)=\"increment()\">Increment</button>\n<><6E><EFBFBD><EFBFBD></div>\n<><6E>`\n})\nexport<72>class<73>CounterComponent<6E>{\n<><6E>count<6E>=<3D>0;\n<><6E>increment()<29>{\n<><6E><EFBFBD><EFBFBD>this.count++;\n<><6E>}\n}",
|
||
language: "javascript"
|
||
}
|
||
]}
|
||
initialSelectedIndex={2}
|
||
/>
|
||
|
||
## Recipe Block
|
||
|
||
Perfect for tutorials, API documentation, or any scenario where you want to guide users through code examples with numbered steps corresponding to specific lines of code.
|
||
|
||
<recipe
|
||
code="import<72>React,<2C>{<7B>useState<74>}<7D>from<6F>'react';
|
||
|
||
function<6F>Counter()<29>{
|
||
<20><>const<73>[count,<2C>setCount]<5D>=<3D>useState(0);
|
||
|
||
<20><>return<72>(
|
||
<20><><EFBFBD><EFBFBD><div>
|
||
<20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><p>Count:<3A>{count}</p>
|
||
<20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><button<6F>onClick={()<29>=><3E>setCount(count<6E>+<2B>1)}>Increment</button>
|
||
<20><><EFBFBD><EFBFBD></div>
|
||
<20><>);
|
||
}
|
||
|
||
export<72>default<6C>Counter;"
|
||
title=""
|
||
description=""
|
||
instruction={[
|
||
{
|
||
itemDescription: "Import the useState hook from React",
|
||
header: "Imports",
|
||
codeLineStart: 1,
|
||
codeLineEnd: 1
|
||
},
|
||
{
|
||
itemDescription: "Define a functional component named Counter",
|
||
header: "Define Component",
|
||
codeLineStart: 3,
|
||
codeLineEnd: 3
|
||
},
|
||
{
|
||
header: "Define State",
|
||
itemDescription:
|
||
"Declare state variable `count` with initial value 0, `setCount` is the updater function",
|
||
codeLineStart: 4,
|
||
codeLineEnd: 4
|
||
},
|
||
{
|
||
itemDescription: "Return JSX to render the UI",
|
||
header: "Render Logic",
|
||
codeLineStart: 7,
|
||
codeLineEnd: 10
|
||
}
|
||
]}
|
||
/>
|
||
|
||
## API Route Block
|
||
|
||
Takes data directly from an OpenAPI spec to populate this component with schema, responses and examples.
|
||
|
||
<apiReference schemaFile="Swagger-Petstore.json|GET:/user/login" />
|
||
|
||
## Directory
|
||
|
||
To convey code architecture or organisation conventions, showing users folder structures helps convey structural ideas that can be tricky to explain textually.
|
||
|
||
The editing experience is smooth with a tailored drag-and-drop interface.
|
||
|
||
<fileStructure
|
||
fileStructure={[
|
||
{ id: "zm0xmlefo", name: "Folder A", type: "folder", parentId: null },
|
||
{ id: "d7bw8ns62", name: "File A.txt", type: "file", parentId: "zm0xmlefo" },
|
||
{
|
||
id: "xaiajws95",
|
||
name: "Subfolder A",
|
||
type: "folder",
|
||
parentId: "zm0xmlefo"
|
||
},
|
||
{ id: "xv64qw84k", name: "Folder B", type: "folder", parentId: null },
|
||
{ id: "beqrd40u0", name: "Subfolder", type: "folder", parentId: "xv64qw84k" },
|
||
{ id: "yijaqtwhg", name: "File B.txt", type: "file", parentId: "beqrd40u0" },
|
||
{ id: "hfv48qb0z", name: "Home Route File.txt", type: "file", parentId: null }
|
||
]}
|
||
caption="An example file structure"
|
||
/>
|
||
|
||
## Mermaid
|
||
|
||
TinaDocs supports [Mermaid.js](https://mermaid.js.org/), to define and render diagrams directly inside Markdown content.
|
||
|
||
This lets you to add flowcharts, sequence diagrams, Gantt charts, and more.
|
||
|
||
The diagram shares the code block node in the editor, but lets you preview what the diagram will look like.
|
||
|
||
<Callout
|
||
body={<>
|
||
Mermaid Rendering is **client-side** only, so server-side previews wont show diagrams
|
||
</>}
|
||
variant="warning"
|
||
/>
|
||
|
||
### Flowcharts
|
||
|
||
```mermaid
|
||
%% This won't render without implementing a rendering engine (e.g. mermaid on npm)
|
||
flowchart TD
|
||
id1(this is an example flow diagram)
|
||
--> id3(Click the top button to preview the changes)
|
||
```
|
||
|
||
### Sequence Diagrams
|
||
|
||
```mermaid
|
||
%% This won't render without implementing a rendering engine (e.g. mermaid on npm)
|
||
sequenceDiagram
|
||
participant Client
|
||
participant API
|
||
participant DB
|
||
|
||
Client->>API: GET /data
|
||
API->>DB: Query data
|
||
DB-->>API: Result
|
||
API-->>Client: Response
|
||
```
|
||
|
||
### State Diagram
|
||
|
||
```mermaid
|
||
stateDiagram-v2
|
||
[*] --> Waiting
|
||
Waiting --> RequestSent: Client calls API
|
||
RequestSent --> Complete: API sends response
|
||
Complete --> [*]
|
||
|
||
```
|
||
|
||
### Class Diagram
|
||
|
||
```mermaid
|
||
classDiagram
|
||
class Client {
|
||
+requestData()
|
||
}
|
||
class API {
|
||
+handleRequest()
|
||
+queryDB()
|
||
}
|
||
class DB {
|
||
+runQuery()
|
||
}
|
||
|
||
Client --> API : calls
|
||
API --> DB : queries
|
||
|
||
```
|
||
|
||
### Pie Chart
|
||
|
||
```mermaid
|
||
pie
|
||
title API Resource Usage
|
||
"Client Requests" : 30
|
||
"API Processing" : 40
|
||
"DB Query Time" : 30
|
||
```
|