262 lines
6.8 KiB
Markdown
262 lines
6.8 KiB
Markdown
# Graph Shortcode Documentation
|
|
|
|
This Hugo site includes a custom shortcode for creating terminal-styled graphs that match the hacker green aesthetic.
|
|
|
|
## Features
|
|
|
|
- **Server-side processing**: Data is processed when Hugo builds the site
|
|
- **Terminal styling**: Automatic green color scheme matching the site theme
|
|
- **Multiple chart types**: Line, bar, pie, doughnut, radar, and more
|
|
- **Responsive**: Adapts to different screen sizes
|
|
- **Customizable**: Override colors and styling as needed
|
|
|
|
## Basic Usage
|
|
|
|
The shortcode supports two modes:
|
|
1. **Inline JSON data** - Embed data directly in your markdown
|
|
2. **CSV file data** - Load data from a CSV file in your page bundle
|
|
|
|
### CSV File Mode (Recommended)
|
|
|
|
Place your CSV file in the same directory as your blog post's `index.md`:
|
|
|
|
```markdown
|
|
{{< graph id="my-chart" type="line" title="My Data" height="500" csv="data.csv" labelColumn="Date" dataColumn="Value" dateFormat="2006-01" >}}
|
|
{{< /graph >}}
|
|
```
|
|
|
|
**CSV Parameters:**
|
|
- `csv` - Filename of the CSV in the page bundle (required for CSV mode)
|
|
- `labelColumn` - Column name for x-axis labels (default: "Month")
|
|
- `dataColumn` - Column name for y-axis data (default: "Questions")
|
|
- `dateFormat` - Go date format for parsing timestamps (default: "2006-01")
|
|
- `skipRows` - Number of rows to skip from the start (default: 0)
|
|
- `maxRows` - Maximum number of rows to display (default: 0 = all)
|
|
|
|
**Example CSV file** (`data.csv`):
|
|
```csv
|
|
Date,Value
|
|
2024-01,100
|
|
2024-02,150
|
|
2024-03,175
|
|
```
|
|
|
|
### Inline JSON Mode
|
|
|
|
### Line Chart
|
|
|
|
```markdown
|
|
{{< graph id="my-chart" type="line" title="My Data" height="400" >}}
|
|
{
|
|
"labels": ["Jan", "Feb", "Mar", "Apr", "May"],
|
|
"datasets": [{
|
|
"label": "Sales",
|
|
"data": [12, 19, 3, 5, 2]
|
|
}]
|
|
}
|
|
{{< /graph >}}
|
|
```
|
|
|
|
### Bar Chart
|
|
|
|
```markdown
|
|
{{< graph id="bar-example" type="bar" title="Monthly Revenue" height="350" >}}
|
|
{
|
|
"labels": ["Q1", "Q2", "Q3", "Q4"],
|
|
"datasets": [{
|
|
"label": "Revenue ($k)",
|
|
"data": [65, 59, 80, 81]
|
|
}]
|
|
}
|
|
{{< /graph >}}
|
|
```
|
|
|
|
### Multiple Datasets
|
|
|
|
```markdown
|
|
{{< graph id="multi-line" type="line" title="Comparison" height="400" >}}
|
|
{
|
|
"labels": ["2020", "2021", "2022", "2023", "2024"],
|
|
"datasets": [
|
|
{
|
|
"label": "Product A",
|
|
"data": [30, 45, 60, 70, 85]
|
|
},
|
|
{
|
|
"label": "Product B",
|
|
"data": [20, 35, 55, 65, 75]
|
|
}
|
|
]
|
|
}
|
|
{{< /graph >}}
|
|
```
|
|
|
|
### Pie Chart
|
|
|
|
```markdown
|
|
{{< graph id="pie-chart" type="pie" title="Market Share" height="400" >}}
|
|
{
|
|
"labels": ["Chrome", "Firefox", "Safari", "Edge"],
|
|
"datasets": [{
|
|
"data": [65, 15, 12, 8]
|
|
}]
|
|
}
|
|
{{< /graph >}}
|
|
```
|
|
|
|
## Parameters
|
|
|
|
### Common Parameters
|
|
|
|
| Parameter | Required | Default | Description |
|
|
|-----------|----------|---------|-------------|
|
|
| `id` | No | Auto-generated | Unique identifier for the chart |
|
|
| `type` | No | `line` | Chart type: `line`, `bar`, `pie`, `doughnut`, `radar`, `polarArea` |
|
|
| `title` | No | Empty | Chart title displayed above the graph |
|
|
| `height` | No | `400` | Height of the chart container in pixels |
|
|
|
|
### CSV Mode Parameters
|
|
|
|
| Parameter | Required | Default | Description |
|
|
|-----------|----------|---------|-------------|
|
|
| `csv` | Yes (for CSV mode) | - | Filename of CSV in page bundle |
|
|
| `labelColumn` | No | `"Month"` | CSV column name for labels (x-axis) |
|
|
| `dataColumn` | No | `"Questions"` | CSV column name for data (y-axis) |
|
|
| `dateFormat` | No | `"2006-01"` | Go date format string for parsing dates |
|
|
| `skipRows` | No | `0` | Number of data rows to skip |
|
|
| `maxRows` | No | `0` | Max rows to display (0 = all) |
|
|
|
|
## Data Format
|
|
|
|
The shortcode expects JSON data in Chart.js format. The basic structure is:
|
|
|
|
```json
|
|
{
|
|
"labels": ["Label 1", "Label 2", "Label 3"],
|
|
"datasets": [{
|
|
"label": "Dataset Name",
|
|
"data": [value1, value2, value3]
|
|
}]
|
|
}
|
|
```
|
|
|
|
### Advanced Data Options
|
|
|
|
You can override the automatic styling by providing Chart.js dataset properties:
|
|
|
|
```markdown
|
|
{{< graph id="custom-style" type="line" title="Custom Colors" >}}
|
|
{
|
|
"labels": ["A", "B", "C"],
|
|
"datasets": [{
|
|
"label": "Custom",
|
|
"data": [10, 20, 30],
|
|
"borderColor": "rgb(255, 99, 132)",
|
|
"backgroundColor": "rgba(255, 99, 132, 0.2)",
|
|
"borderWidth": 3
|
|
}]
|
|
}
|
|
{{< /graph >}}
|
|
```
|
|
|
|
## Color Scheme
|
|
|
|
The shortcode automatically applies terminal-style colors:
|
|
|
|
- **Primary**: `rgb(173, 255, 47)` (greenyellow)
|
|
- **Secondary**: `rgb(0, 255, 0)` (green)
|
|
- **Tertiary**: `rgb(0, 200, 0)` (darker green)
|
|
- **Grid**: `rgba(0, 255, 0, 0.2)`
|
|
- **Background**: `rgba(0, 255, 0, 0.1)`
|
|
|
|
Multiple datasets automatically cycle through these colors.
|
|
|
|
## CSS Classes
|
|
|
|
The graph container has the class `.graph-container` with the following variants:
|
|
|
|
- `.graph-container.full-width` - Full width graph (extends to edges)
|
|
- `.graph-container.compact` - Smaller padding and title
|
|
|
|
To use variants, wrap the shortcode in a div:
|
|
|
|
```html
|
|
<div class="graph-container compact">
|
|
{{< graph ... >}}
|
|
...
|
|
{{< /graph >}}
|
|
</div>
|
|
```
|
|
|
|
## Examples
|
|
|
|
### StackOverflow Decline
|
|
|
|
```markdown
|
|
{{< graph id="stackoverflow" type="line" title="Stack Overflow Activity" height="400" >}}
|
|
{
|
|
"labels": ["2018", "2019", "2020", "2021", "2022", "2023", "2024"],
|
|
"datasets": [{
|
|
"label": "Questions (thousands/month)",
|
|
"data": [170, 180, 195, 175, 150, 120, 85],
|
|
"fill": true
|
|
}]
|
|
}
|
|
{{< /graph >}}
|
|
```
|
|
|
|
### Technology Adoption
|
|
|
|
```markdown
|
|
{{< graph id="tech-adoption" type="bar" title="Framework Adoption (%)" height="350" >}}
|
|
{
|
|
"labels": ["React", "Vue", "Angular", "Svelte"],
|
|
"datasets": [{
|
|
"label": "2023",
|
|
"data": [67, 45, 42, 18]
|
|
}, {
|
|
"label": "2024",
|
|
"data": [71, 48, 38, 25]
|
|
}]
|
|
}
|
|
{{< /graph >}}
|
|
```
|
|
|
|
### Response Time Distribution
|
|
|
|
```markdown
|
|
{{< graph id="response-times" type="doughnut" title="API Response Times" height="400" >}}
|
|
{
|
|
"labels": ["< 100ms", "100-500ms", "500ms-1s", "> 1s"],
|
|
"datasets": [{
|
|
"data": [45, 35, 15, 5]
|
|
}]
|
|
}
|
|
{{< /graph >}}
|
|
```
|
|
|
|
## Tips
|
|
|
|
1. **Keep IDs unique**: Each chart on a page needs a unique ID
|
|
2. **Data validation**: The shortcode validates JSON at build time - invalid JSON will cause build errors
|
|
3. **Responsive**: Charts are responsive by default, but fixed heights work better for consistency
|
|
4. **Performance**: Charts are rendered client-side but data is embedded at build time
|
|
5. **Testing**: Set `draft: false` and run `hugo server -D` to preview graphs
|
|
|
|
## Troubleshooting
|
|
|
|
**Graph not showing?**
|
|
- Check browser console for JavaScript errors
|
|
- Verify Chart.js is loaded (should be in page `<head>`)
|
|
- Ensure JSON data is valid
|
|
- Check that the ID is unique on the page
|
|
|
|
**Styling issues?**
|
|
- Graphs inherit the terminal theme automatically
|
|
- Custom colors can be added per dataset
|
|
- Container styling can be modified in `assets/sass/partials/_graphs.scss`
|
|
|
|
**Build errors?**
|
|
- Invalid JSON will cause Hugo build failures
|
|
- Check for unclosed braces or missing commas
|
|
- Ensure the shortcode tags are properly formatted
|