Skip to content

Commit b600a9d

Browse files
authored
Merge pull request #6 from ps-wiki/database
Add JSON format database
2 parents 7061cc8 + e0c1866 commit b600a9d

File tree

294 files changed

+7505
-144
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

294 files changed

+7505
-144
lines changed

.github/workflows/deploy.yml

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -86,10 +86,23 @@ jobs:
8686
valueFile: "_config.yml"
8787
propertyPath: "giscus.repo"
8888
value: ${{ github.repository }}
89-
- name: Install and Build 🔧
89+
- name: Install OS packages (ImageMagick)
90+
run: |
91+
sudo apt-get update
92+
sudo apt-get install -y imagemagick
93+
- name: Install Python deps
9094
run: |
91-
sudo apt-get update && sudo apt-get install -y imagemagick
9295
pip3 install --upgrade nbconvert
96+
pip3 install -r database/requirements.txt
97+
- name: Convert JSON → Markdown
98+
run: |
99+
python database/pyscripts/json2md_all.py \
100+
--in-dir database/json \
101+
--out-dir _wiki \
102+
--pattern "*.json" \
103+
--fail-fast
104+
- name: Build Jekyll site
105+
run: |
93106
export JEKYLL_ENV=production
94107
bundle exec jekyll build
95108
- name: Purge unused CSS 🧹

.gitignore

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,4 +10,10 @@ Gemfile.lock
1010
assets/libs/
1111
node_modules/
1212
vendor
13-
.idea
13+
.idea
14+
15+
# Ignore python cache files
16+
__pycache__/
17+
18+
# local test wiki markdown files
19+
_wikitest/

README.md

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,105 @@ A custom [wiki layout](./_layouts/wiki.liquid) adapted from the `distill` layout
2626
- **Direct Editing**: A link to edit the term directly on GitHub
2727
- **Community Engagement**: Integrated Giscus comments
2828

29+
## Database
30+
31+
The folder `database` contains the source data and scripts for generating the wiki:
32+
33+
- Folder `database/json` contains the source JSON files for the wiki.
34+
- Folder `database/pyscripts` contains Python scripts for processing the data.
35+
36+
### Example JSON File
37+
38+
Use [stability.json](./database/json/stability.json) as a reference for creating new term entries.
39+
Below is an example structure of a JSON file for a term:
40+
41+
```json
42+
{
43+
"id": "example-term",
44+
"title": "Example Term",
45+
"description": "A concise description of this concept.",
46+
"language": "en",
47+
"tags": [
48+
// existing tags: https://ps-wiki.github.io/wiki-tag/#all-tags
49+
"tag1",
50+
"tag2"
51+
],
52+
"related": ["other-term-id-1", "other-term-id-2"],
53+
"version": "1.0.0", // SemVer version of this term entry
54+
"breaking": false, // set to true if there are breaking changes of this term compared to previous version
55+
"dates": {
56+
"created": "2025-11-01",
57+
"last_modified": "2025-11-01"
58+
},
59+
"authors": [
60+
{
61+
"name": "Contributor Name",
62+
"url": "https://example.com"
63+
},
64+
{
65+
"name": "Another Contributor",
66+
"url": "https://example.org"
67+
}
68+
],
69+
"content": {
70+
"sections": [
71+
{
72+
"order": 1,
73+
"id": "definition-by-institution1",
74+
"title": "Definition by Institution 1",
75+
"type": "definition", // "definition" for quoted content, "note" for others
76+
"source_keys": [
77+
"key1" // ensure the key exists in assets/bibliography/papers.bib
78+
],
79+
"page": "p45", // or "p45, Revision 2" if applicable to indicate specific revision
80+
"body_md": "> The ability of an electric power system to maintain a state of equilibrium during normal and abnormal conditions or disturbances.\n",
81+
"figures": []
82+
},
83+
{
84+
"order": 2,
85+
"id": "elaboration-in-article",
86+
"title": "Elaboration in an Article",
87+
"type": "definition",
88+
"source_keys": [],
89+
"page": null,
90+
"body_md": "This section elaborates on the concept, its relevance, or provides historical context.\n",
91+
"figures": [
92+
{
93+
"path": "/assets/img/pswiki/example-figure.png",
94+
"caption_md": "Fig. 1. Example figure caption. (from <d-cite key=\"example2024reference\"></d-cite>)",
95+
"zoomable": true,
96+
"source_keys": ["example2024reference"]
97+
}
98+
]
99+
}
100+
]
101+
}
102+
}
103+
```
104+
105+
Following conventions should be observed when creating or editing term JSON files:
106+
107+
- File Naming: Each term is stored in a separate JSON file named `<term-id>.json`.
108+
- The `id` field should match the filename, e.g. stability.json → "id": "stability".
109+
- The `source_keys` in each section and figure should correspond to entries in the bibliography file located at `assets/bibliography/papers.bib`.
110+
- The `body_md` field contains the main content in Markdown format. Use standard Markdown syntax for headings, lists, and formatting.
111+
- Figures should be stored in the `assets/img/pswiki/` directory, and their paths should be correctly referenced in the JSON.
112+
- In each figure entry: 1) Use a relative path such as "/assets/img/pswiki/example-figure.png". 2) Include a concise caption_md (in Markdown) and the relevant source_keys. 3) Set "zoomable": true for figures intended to support click-to-zoom in Jekyll.
113+
114+
### Conda Environment
115+
116+
Use the following command to create the conda environment for local development:
117+
118+
```
119+
conda env create --file ./pswiki/database/environment.yml
120+
```
121+
122+
Use the following command to export minimal-history export (only explicit user-installed packages)
123+
124+
```
125+
conda env export --from-history --file ./pswiki/database/environment.yml
126+
```
127+
29128
## License
30129

31130
This project is licensed under the [CC-BY-NC 4.0](./LICENSE).

_layouts/wiki.liquid

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -167,7 +167,13 @@
167167

168168
<div class="col-12 mb-2">
169169
{% if site.repo and site.branch %}
170-
<a href="https://github.com/{{ site.repo }}/edit/{{ site.branch }}/{{ page.path }}" class="wiki-nav-link"> Edit This Page </a>
170+
{% assign json_path = page.path | replace: '_wiki/', 'database/json/' | replace: '.md', '.json' %}
171+
<a
172+
href="https://github.com/{{ site.repo }}/edit/{{ site.branch }}/{{ json_path }}"
173+
class="wiki-nav-link"
174+
>
175+
Edit Source JSON
176+
</a>
171177
{% endif %}
172178
</div>
173179

_pages/changelog.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,11 @@ This page records major changes in this wiki.
1313

1414
## 2025
1515

16+
### 11-01
17+
18+
- Add JSON based database, now the term is mainly stored in JSON files
19+
- Add pyscripts to convert between JSON and MD
20+
1621
### 10-30
1722

1823
- Add terms

_pages/wiki-quicklink.md

Lines changed: 0 additions & 44 deletions
This file was deleted.
File renamed without changes.

_wiki/adequacy.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ description: The ability to supply the demand and energy requirements of the end
44
tags:
55
- reliability
66
- nerc
7+
related: []
78
authors:
89
- name: Jinning Wang
910
url: https://jinningwang.github.io

_wiki/ambient-adjusted-ratings.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,11 @@
11
---
22
title: Ambient-Adjusted Ratings
3-
description:
3+
description:
44
tags:
55
- system-operator
66
- grid-enhancing-technology
77
- transmission
8+
related: []
89
authors:
910
- name: Jinning Wang
1011
url: https://jinningwang.github.io

_wiki/ancillary-service.md renamed to _wiki/ancillary-services.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ tags:
66
- reliability
77
- ferc
88
- nerc
9+
related: []
910
authors:
1011
- name: Jinning Wang
1112
url: https://jinningwang.github.io

0 commit comments

Comments
 (0)