initial commit after project creation
This commit is contained in:
Gerhard Scheikl
253
content/docs/tinadocs-features/code-components.mdx
Normal file
253
content/docs/tinadocs-features/code-components.mdx
Normal file
@@ -0,0 +1,253 @@
|
||||
---
|
||||
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
|
||||
```
|
||||
Reference in New Issue
Block a user