Skip to content

Commit b9b5ab5

Browse files
ttuffttuff
authored
Merge pull request #6 from CU-ESIIL/codex/upgrade-documentation-website-template
Enhance MkDocs starter with richer homepage and reusable examples
2 parents 7836702 + ecfc226 commit b9b5ab5

4 files changed

Lines changed: 180 additions & 32 deletions

File tree

‎docs/examples.md‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
# UI Examples
2+
3+
This page contains small, copyable patterns you can reuse across the site.
4+
5+
## Hoverable button
6+
7+
Use this for a small call-to-action with a subtle hover effect.
8+
9+
<a class="md-button oasis-hover-button" href="#">Example hover button</a>
10+
11+
```html
12+
<a class="md-button oasis-hover-button" href="#">Example hover button</a>
13+
```
14+
15+
## Responsive iframe embed
16+
17+
Use this wrapper to keep embedded content responsive.
18+
19+
<div class="oasis-embed">
20+
<iframe
21+
title="Example map embed"
22+
src="https://www.openstreetmap.org/export/embed.html?bbox=-105.3%2C39.9%2C-104.9%2C40.1&amp;layer=mapnik"
23+
loading="lazy"
24+
allowfullscreen>
25+
</iframe>
26+
</div>
27+
28+
```html
29+
<div class="oasis-embed">
30+
<iframe
31+
title="Example embed"
32+
src="https://example.com"
33+
loading="lazy"
34+
allowfullscreen>
35+
</iframe>
36+
</div>
37+
```
38+
39+
## Card grid
40+
41+
Use card grids to present parallel links or content categories.
42+
43+
<div class="grid cards" markdown>
44+
45+
- **Guide**
46+
47+
---
48+
49+
Link short onboarding content.
50+
51+
- **Workflow**
52+
53+
---
54+
55+
Summarize repeatable project steps.
56+
57+
- **Reference**
58+
59+
---
60+
61+
Point to key files and definitions.
62+
63+
</div>
64+
65+
```md
66+
<div class="grid cards" markdown>
67+
68+
- **Guide**
69+
70+
---
71+
72+
Link short onboarding content.
73+
74+
- **Workflow**
75+
76+
---
77+
78+
Summarize repeatable project steps.
79+
80+
- **Reference**
81+
82+
---
83+
84+
Point to key files and definitions.
85+
86+
</div>
87+
```
88+
89+
## Content tabs
90+
91+
Use tabs when two or three variants should live in one place.
92+
93+
=== "Python"
94+
95+
```python
96+
print("Hello from Python")
97+
```
98+
99+
=== "R"
100+
101+
```r
102+
print("Hello from R")
103+
```
104+
105+
## Admonition
106+
107+
Use callouts for important notes or caution points.
108+
109+
!!! tip
110+
Keep examples short and focused so future contributors can copy and adapt them quickly.

‎docs/index.md‎

Lines changed: 23 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,31 @@
11
# basic_OASIS
22

3-
<p style="text-align: right;"><a href="https://github.com/CU-ESIIL/basic_OASIS/edit/main/docs/index.md" title="Edit this page">✏️ Edit this page</a></p>
3+
Welcome to `basic_OASIS`, a lightweight documentation starter built with MkDocs + Material. Use this as a clean baseline for project notes, quick guides, and student-facing documentation.
44

5-
![Project hero image](assets/hero.jpg)
5+
[Get Started](examples.md){ .md-button .md-button--primary }
6+
[View Repository](https://github.com/CU-ESIIL/basic_OASIS){ .md-button }
67

7-
Welcome to the minimal project website.
8+
<div class="grid cards" markdown>
89

9-
## What stays
10+
- :material-code-tags: **Code**
1011

11-
- A clean header and styling.
12-
- A sidebar for site navigation.
13-
- Browser-based editing through the GitHub edit link.
12+
---
1413

15-
## Quick edit guide
14+
Keep setup steps, scripts, and reproducible snippets in one place.
1615

17-
1. Open `docs/index.md`.
18-
2. Click the ✏️ icon (or use the link above).
19-
3. Commit your changes.
16+
- :material-database: **Data**
17+
18+
---
19+
20+
Share data access notes, schemas, and provenance details clearly.
21+
22+
- :material-file-document-outline: **Docs**
23+
24+
---
25+
26+
Build concise guides that are easy to maintain and extend over time.
27+
28+
</div>
29+
30+
!!! note "Template-first by design"
31+
This site is intentionally minimal. Treat it as a starter template and extend only what your project needs.

‎docs/stylesheets/extra.css‎

Lines changed: 37 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,47 @@
1-
/*
2-
* Additional customizations for the Project OASIS documentation site.
3-
*
4-
* This file replaces the stylesheet that used to be generated by the
5-
* bootstrap automation workflow. It intentionally keeps the overrides
6-
* lightweight so that future teams can extend them as needed while
7-
* ensuring MkDocs always has a valid asset to load during builds.
8-
*/
1+
/* Central extension point for lightweight, reusable visual tweaks. */
92

103
:root {
11-
/* Provide a subtle brand accent that matches the ESIIL palette. */
124
--oasis-accent: #135d7f;
135
}
146

15-
/* Make hero images and other wide media scale gracefully. */
16-
.md-content img {
17-
border-radius: 6px;
18-
box-shadow: 0 4px 12px rgba(0, 0, 0, 0.12);
7+
/* Keep homepage hero content a bit more breathable. */
8+
.md-content h1 {
9+
margin-bottom: 0.5rem;
1910
}
2011

21-
/* Improve the spacing for long bullet lists used in the templates. */
22-
.md-typeset ul {
23-
margin-bottom: 0.8em;
12+
.md-content > p:first-of-type {
13+
font-size: 1.05rem;
14+
max-width: 68ch;
2415
}
2516

26-
/* Highlight inline code a little more to help with command visibility. */
27-
.md-typeset code {
28-
background-color: rgba(19, 93, 127, 0.08);
29-
border-radius: 4px;
30-
padding: 0.1rem 0.25rem;
17+
/* Subtle polish for Material buttons used across docs. */
18+
.md-button {
19+
border-radius: 999px;
20+
}
21+
22+
.oasis-hover-button {
23+
transition: transform 0.15s ease, box-shadow 0.15s ease;
24+
}
25+
26+
.oasis-hover-button:hover {
27+
transform: translateY(-1px);
28+
box-shadow: 0 0.3rem 0.9rem rgba(19, 93, 127, 0.22);
29+
}
30+
31+
/* Reusable responsive embed wrapper for iframes and maps. */
32+
.oasis-embed {
33+
position: relative;
34+
width: 100%;
35+
padding-top: 56.25%;
36+
border-radius: 0.5rem;
37+
overflow: hidden;
38+
box-shadow: 0 0.2rem 0.8rem rgba(0, 0, 0, 0.12);
39+
}
40+
41+
.oasis-embed iframe {
42+
position: absolute;
43+
inset: 0;
44+
width: 100%;
45+
height: 100%;
46+
border: 0;
3147
}

‎mkdocs.yml‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ edit_uri: "edit/main/docs/"
99
nav:
1010
- Site:
1111
- Home: index.md
12+
- Examples: examples.md
1213

1314
theme:
1415
name: material
@@ -20,6 +21,15 @@ theme:
2021
- navigation.top
2122
- toc.integrate
2223

24+
markdown_extensions:
25+
- admonition
26+
- attr_list
27+
- md_in_html
28+
- pymdownx.details
29+
- pymdownx.superfences
30+
- pymdownx.tabbed:
31+
alternate_style: true
32+
2333
extra_css:
2434
- stylesheets/extra.css
2535

0 commit comments

Comments
 (0)