Skip to content

Commit 3baa7b1

Browse files
nikoschamnikoscham
committed
Scaffold versioned Docusaurus site
1 parent 123650e commit 3baa7b1

16 files changed

Lines changed: 18524 additions & 2 deletions

File tree

‎.github/workflows/deploy.yml‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
name: Deploy documentation
2+
3+
on:
4+
push:
5+
branches: [main]
6+
workflow_dispatch:
7+
8+
permissions:
9+
contents: read
10+
pages: write
11+
id-token: write
12+
13+
concurrency:
14+
group: pages
15+
cancel-in-progress: true
16+
17+
jobs:
18+
build:
19+
runs-on: ubuntu-latest
20+
steps:
21+
- uses: actions/checkout@v4
22+
- uses: actions/setup-node@v4
23+
with:
24+
node-version: 22
25+
cache: npm
26+
- run: npm ci
27+
- run: npm run build
28+
- uses: actions/upload-pages-artifact@v3
29+
with:
30+
path: build
31+
32+
deploy:
33+
needs: build
34+
runs-on: ubuntu-latest
35+
environment:
36+
name: github-pages
37+
url: ${{ steps.deployment.outputs.page_url }}
38+
steps:
39+
- id: deployment
40+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
/node_modules
2+
/build
3+
.docusaurus
4+
.cache-loader
5+
.DS_Store
6+
.env*
7+
npm-debug.log*

‎README.md‎

Lines changed: 33 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,39 @@
22

33
# FEAScript-documentation
44

5-
> Central place (work in progress) for assembling user & developer documentation for the FEAScript project.
5+
User & developer documentation for the FEAScript project, published at **https://doc.feascript.com**. Built with [Docusaurus](https://docusaurus.io/) (Node.js >= 20).
6+
7+
## Local development
8+
9+
```bash
10+
npm install
11+
npm start # dev server with live reload
12+
npm run build # production build into ./build
13+
npm run serve # serve the production build locally
14+
```
15+
16+
## Writing docs
17+
18+
- Pages are Markdown/MDX files under `docs/`; the sidebar is defined in `sidebars.js`.
19+
- Math is supported with KaTeX: inline `$T$` and block `$$ ... $$`.
20+
- `docs/` always holds the **unreleased** docs ("Next" in the version dropdown).
21+
22+
## Versioning
23+
24+
When a new FEAScript-core version is released, snapshot the current docs:
25+
26+
```bash
27+
npm run version -- 0.3.0
28+
```
29+
30+
This copies `docs/` to `versioned_docs/version-0.3.0/`, the sidebar to `versioned_sidebars/`, and records the version in `versions.json`. Released docs are then available at `doc.feascript.com/0.3.0/...` and appear in the version dropdown.
31+
32+
After the first release, edit `docusaurus.config.js`: remove `lastVersion: "current"` so the newest released version becomes the default (unversioned URLs). Fixes to an old version are made directly in its `versioned_docs/version-x.y.z/` folder.
33+
34+
## Deployment
35+
36+
Pushing to `main` triggers [`.github/workflows/deploy.yml`](.github/workflows/deploy.yml), which builds the site and deploys it to `doc.feascript.com`
637

738
## License
839

9-
The content of the FEAScript documentation is licensed under <a href="https://github.com/FEAScript/FEAScript-documentation/blob/main/LICENSE" target="_blank">CC-BY 4.0</a>. Note that the core library of FEAScript is distributed under the terms of the <a href="https://github.com/FEAScript/FEAScript-core/blob/main/LICENSE" target="_blank">MIT license</a>.
40+
The content of the FEAScript documentation is licensed under <a href="https://github.com/FEAScript/FEAScript-documentation/blob/main/LICENSE" target="_blank">CC-BY 4.0</a>. Note that the core library of FEAScript is distributed under the terms of the <a href="https://github.com/FEAScript/FEAScript-core/blob/main/LICENSE" target="_blank">MIT license</a>.

‎docs/getting-started/first-simulation.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
sidebar_position: 2
3+
---
4+
5+
# Your first simulation
6+
7+
:::info
8+
This page is a placeholder. Complete, runnable examples are available in the
9+
[examples directory](https://github.com/FEAScript/FEAScript-core/tree/main/examples) of FEAScript-core.
10+
:::
11+
12+
A FEAScript simulation typically consists of the following steps:
13+
14+
1. Create a `FEAScriptModel`.
15+
2. Select the solver and the physics model.
16+
3. Define the mesh configuration.
17+
4. Apply the boundary conditions.
18+
5. Solve and post-process the results.

‎docs/getting-started/installation.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
sidebar_position: 1
3+
---
4+
5+
# Installation
6+
7+
## In the browser
8+
9+
Import the ES module build from the hosted build or from a CDN:
10+
11+
```html
12+
<script type="module">
13+
import { FEAScriptModel } from "https://core.feascript.com/dist/feascript.esm.js";
14+
</script>
15+
```
16+
17+
```html
18+
<script type="module">
19+
import { FEAScriptModel } from "https://cdn.jsdelivr.net/gh/FEAScript/FEAScript-core/dist/feascript.esm.js";
20+
</script>
21+
```
22+
23+
You can also download a release from [GitHub Releases](https://github.com/FEAScript/FEAScript-core/releases) and import it locally.
24+
25+
## With Node.js
26+
27+
```bash
28+
npm install feascript
29+
```
30+
31+
```javascript
32+
import { FEAScriptModel } from "feascript";
33+
```
34+
35+
FEAScript is built as an ES module. In a new project, set `"type": "module"` in your `package.json`.

‎docs/intro.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
slug: /
3+
sidebar_position: 1
4+
---
5+
6+
# Introduction
7+
8+
**FEAScript** is a finite element simulation library developed in JavaScript. It enables engineering simulations in both browser-based and server-side (Node.js) environments, without the overhead of traditional desktop software.
9+
10+
:::caution
11+
FEAScript is under heavy development. Its functionality and interfaces may change rapidly. Use the version selector in the navigation bar to read the documentation that matches the release you are using.
12+
:::
13+
14+
## Features
15+
16+
- **Physics models:** creeping (Stokes) flow, Euler-Bernoulli beam bending, front propagation, heat conduction, general form PDE (linear and nonlinear)
17+
- **Meshing:** simple 1D/2D mesh generation, unstructured mesh import from Gmsh (`.msh`)
18+
- **Solvers:** frontal, Jacobi (CPU/WebGPU) and LU, Newton–Raphson for nonlinear systems
19+
- **Performance:** web worker support for multi-threaded computation
20+
- **Visualization:** interactive rendering with vtk.js and Plotly
21+
22+
## Where to go next
23+
24+
- [Installation](./getting-started/installation.md) – use FEAScript in the browser or with Node.js
25+
- [Your first simulation](./getting-started/first-simulation.md)
26+
- [Heat conduction model](./models/heat-conduction.md)

‎docs/models/heat-conduction.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Heat conduction
2+
3+
Steady-state heat conduction is governed by
4+
5+
$$
6+
-\nabla \cdot \left( k \, \nabla T \right) = Q
7+
$$
8+
9+
where $T$ is the temperature, $k$ is the thermal conductivity, and $Q$ is the volumetric heat source.
10+
11+
:::info
12+
This page is a placeholder. See the
13+
[heat conduction examples](https://github.com/FEAScript/FEAScript-core/tree/main/examples/heatConductionScript)
14+
for working code.
15+
:::

‎docusaurus.config.js‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
// @ts-check
2+
import { themes as prismThemes } from "prism-react-renderer";
3+
import remarkMath from "remark-math";
4+
import rehypeKatex from "rehype-katex";
5+
6+
/** @type {import('@docusaurus/types').Config} */
7+
const config = {
8+
title: "FEAScript Documentation",
9+
tagline: "Finite element simulation library built in JavaScript",
10+
favicon: "img/favicon.ico",
11+
12+
url: "https://doc.feascript.com",
13+
baseUrl: "/",
14+
15+
organizationName: "FEAScript",
16+
projectName: "FEAScript-documentation",
17+
trailingSlash: false,
18+
19+
onBrokenLinks: "throw",
20+
markdown: {
21+
hooks: {
22+
onBrokenMarkdownLinks: "throw",
23+
},
24+
},
25+
26+
i18n: {
27+
defaultLocale: "en",
28+
locales: ["en"],
29+
},
30+
31+
presets: [
32+
[
33+
"classic",
34+
/** @type {import('@docusaurus/preset-classic').Options} */
35+
({
36+
docs: {
37+
routeBasePath: "/",
38+
sidebarPath: "./sidebars.js",
39+
editUrl: "https://github.com/FEAScript/FEAScript-documentation/tree/main/",
40+
remarkPlugins: [remarkMath],
41+
rehypePlugins: [rehypeKatex],
42+
// "current" holds the unreleased docs; released versions are snapshots (see README)
43+
lastVersion: "current",
44+
versions: {
45+
current: { label: "Next (0.3.0-RC)" },
46+
},
47+
},
48+
blog: false,
49+
theme: {
50+
customCss: "./src/css/custom.css",
51+
},
52+
}),
53+
],
54+
],
55+
56+
stylesheets: [
57+
{
58+
href: "https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.css",
59+
type: "text/css",
60+
crossorigin: "anonymous",
61+
},
62+
],
63+
64+
themes: [
65+
[
66+
"@easyops-cn/docusaurus-search-local",
67+
/** @type {import("@easyops-cn/docusaurus-search-local").PluginOptions} */
68+
({
69+
hashed: true,
70+
indexBlog: false,
71+
docsRouteBasePath: "/",
72+
}),
73+
],
74+
],
75+
76+
themeConfig:
77+
/** @type {import('@docusaurus/preset-classic').ThemeConfig} */
78+
({
79+
navbar: {
80+
title: "FEAScript",
81+
logo: { alt: "FEAScript Logo", src: "img/logo.svg" },
82+
items: [
83+
{
84+
type: "docSidebar",
85+
sidebarId: "docsSidebar",
86+
position: "left",
87+
label: "Docs",
88+
},
89+
{ type: "docsVersionDropdown", position: "right" },
90+
{ href: "https://feascript.com", label: "Website", position: "right" },
91+
{
92+
href: "https://github.com/FEAScript/FEAScript-core",
93+
label: "GitHub",
94+
position: "right",
95+
},
96+
],
97+
},
98+
footer: {
99+
style: "dark",
100+
links: [
101+
{
102+
title: "FEAScript",
103+
items: [
104+
{ label: "Website", href: "https://feascript.com" },
105+
{ label: "Studio", href: "https://studio.feascript.com" },
106+
{ label: "Blog", href: "https://blog.feascript.com" },
107+
],
108+
},
109+
{
110+
title: "Community",
111+
items: [
112+
{ label: "GitHub", href: "https://github.com/FEAScript" },
113+
{ label: "Contributing", href: "https://github.com/FEAScript/FEAScript-core/blob/main/CONTRIBUTING.md" },
114+
],
115+
},
116+
],
117+
copyright: `Documentation licensed under CC-BY 4.0. The FEAScript core library is MIT licensed.`,
118+
},
119+
prism: {
120+
theme: prismThemes.github,
121+
darkTheme: prismThemes.dracula,
122+
additionalLanguages: ["bash"],
123+
},
124+
}),
125+
};
126+
127+
export default config;

0 commit comments

Comments
 (0)