decent template for our websites #188

New Issue

despiegk · 2025-02-21T12:55:33Z

despiegk commented

2025-02-21 12:55:33 +00:00

we need a decent template we can use for all our websites and later for our customers, the output needs to be clean html/js.

requirements

Zola (newest release) or Svelte as site builder or Astro
tailwind (v4) or picocss
dark/white theme (user can select)
KEEP IT SIMPLE !!!!
99% can be done in markdown
reusable components
some components can be custom per site e.g. for animation, the styling needs to be in the component
components need to be independent from each other and have no dependencies on other .css... files
we need to support chartjs
we need support for mermaid
the more we make it re-usable and simple the better
the idea is we can use this for the TFGrid 4.0 customers to build and publish their websites

remarks

there will be less control over layout
picocss might be an easier way, use css as how it was intended (be careful how to use it)
the font styles, identation, paging, ... need to be in 1 reusable CSS, so its easy for someone to change the generic theme and this works over the components
everything needs to be super clean (the more simple the better)

possible alternative = SvelteKit

svelte (without server side component, so we can always export to javascript/html)
- https://madewithsvelte.com/svelte-chartjs
- use SvelteKit as static site generator
there is great support for markdown in svelte
create svelte components
we can then also have dynamic components
make sure the use bun and svelte (is super fast & easy)

possible alternative 2 = Astro

https://github.com/withastro/astro
astro is probably the most popular website builder today, lots and lots of templates
if we use, use bun and make clean

tips Zola

Using Markdown Render Hooks (For Advanced Customization)
Zola supports render hooks for customizing how specific elements (like images or links) are processed.

in config

[markdown]
render_emoji = true
external_links_target_blank = true
smart_punctuation = true

📂 templates/shortcodes/figure.html

<figure>
    <img src="{{ src }}" alt="{{ caption }}">
    <figcaption>{{ caption }}</figcaption>
</figure>

Then in markdown:

{{ figure(src="path/to/image.jpg", caption="An image component") }}

we need a decent template we can use for all our websites and later for our customers, the output needs to be clean html/js. ## requirements - [ ] Zola (newest release) or Svelte as site builder or Astro - [ ] tailwind (v4) or picocss - [ ] dark/white theme (user can select) - [ ] KEEP IT SIMPLE !!!! - [ ] 99% can be done in markdown - [ ] reusable components - [ ] some components can be custom per site e.g. for animation, the styling needs to be in the component - [ ] components need to be independent from each other and have no dependencies on other .css... files - [ ] we need to support chartjs - [ ] we need support for mermaid - [ ] the more we make it re-usable and simple the better - [ ] the idea is we can use this for the TFGrid 4.0 customers to build and publish their websites **remarks** - there will be less control over layout - picocss might be an easier way, use css as how it was intended (be careful how to use it) - the font styles, identation, paging, ... need to be in 1 reusable CSS, so its easy for someone to change the generic theme and this works over the components - everything needs to be super clean (the more simple the better) **possible alternative = SvelteKit** - svelte (without server side component, so we can always export to javascript/html) - https://madewithsvelte.com/svelte-chartjs - use SvelteKit as static site generator - there is great support for markdown in svelte - create svelte components - we can then also have dynamic components - make sure the use bun and svelte (is super fast & easy) **possible alternative 2 = Astro** - https://github.com/withastro/astro - astro is probably the most popular website builder today, lots and lots of templates - if we use, use bun and make clean ## tips Zola Using Markdown Render Hooks (For Advanced Customization) Zola supports render hooks for customizing how specific elements (like images or links) are processed. in config ```toml [markdown] render_emoji = true external_links_target_blank = true smart_punctuation = true ``` 📂 templates/shortcodes/figure.html ```html <figure> <img src="{{ src }}" alt="{{ caption }}"> <figcaption>{{ caption }}</figcaption> </figure> ``` Then in markdown: ```markdown {{ figure(src="path/to/image.jpg", caption="An image component") }} ```

sashaastiadi commented

2025-02-21 12:58:27 +00:00

Step by step

for the template

1. Create the Shortcode (HTML Template)

<figure>
    <img src="{{ src }}" alt="{{ caption }}">
    <figcaption>{{ caption }}</figcaption>
</figure>

2. Define the CSS Styles

To ensure proper formatting, add styles for figure elements in your CSS file (e.g., static/style.css or your main stylesheet):

figure {
    display: flex;
    flex-direction: column;
    align-items: center;
    margin: 1em 0;
}

figure img {
    max-width: 100%;
    height: auto;
    border-radius: 8px;
}

figcaption {
    margin-top: 0.5em;
    font-size: 0.9rem;
    color: #666;
    text-align: center;
}

3. Use the Shortcode in index.md (or Any Markdown File)

{{ figure(src="path/to/image.jpg", caption="An image component") }}
This will automatically generate the styled HTML structure from Step 1.

Summary

1️⃣ Create the HTML shortcode (figure.html).
2️⃣ Style it using CSS and make sure the stylesheet is linked in your theme.
3️⃣ Use the shortcode inside your Markdown files (e.g., index.md).

# Step by step for the template ## 1. Create the Shortcode (HTML Template) ``` <figure> <img src="{{ src }}" alt="{{ caption }}"> <figcaption>{{ caption }}</figcaption> </figure> ``` ## 2. Define the CSS Styles To ensure proper formatting, add styles for figure elements in your CSS file (e.g., static/style.css or your main stylesheet): ``` figure { display: flex; flex-direction: column; align-items: center; margin: 1em 0; } figure img { max-width: 100%; height: auto; border-radius: 8px; } figcaption { margin-top: 0.5em; font-size: 0.9rem; color: #666; text-align: center; } ``` ## 3. Use the Shortcode in index.md (or Any Markdown File) `{{ figure(src="path/to/image.jpg", caption="An image component") }} ` This will automatically generate the styled HTML structure from Step 1. --- ## Summary 1️⃣ Create the HTML shortcode (figure.html). 2️⃣ Style it using CSS and make sure the stylesheet is linked in your theme. 3️⃣ Use the shortcode inside your Markdown files (e.g., index.md).

ehab was assigned by sashaastiadi

2025-02-21 12:58:47 +00:00

sashaastiadi self-assigned this 2025-02-21 12:58:58 +00:00

despiegk commented

2025-02-22 05:01:45 +00:00

did quite some more research

astro & astro starlight might be a good choice (starlight as alternative to docusaurus, is layer on astro)

why

astro became one of the most used static generators
astro is compatible with svelte, react, ...
astro has very good tools for importing data one is turso sql (sqlite based) which is very cool
the starlight is +- same as docusaurus
we can have one base for all usecases

the eventual goal is, people write some markdown, and the framework populates HTML site which can then be served over myceliym using an flist

did quite some more research - astro & astro starlight might be a good choice (starlight as alternative to docusaurus, is layer on astro) why - astro became one of the most used static generators - astro is compatible with svelte, react, ... - astro has very good tools for importing data one is turso sql (sqlite based) which is very cool - the starlight is +- same as docusaurus - we can have one base for all usecases the eventual goal is, people write some markdown, and the framework populates HTML site which can then be served over myceliym using an flist

sashaastiadi commented

2025-03-03 09:32:07 +00:00

@despiegk me and ehab did some research and took a look at astro
and i think astro is complicated for marketingpeople to use.

it would be easier for non tech people to edit website content if we just use the old way :
zola + tailwind css + markdown shortcodes

1️⃣ Create the HTML shortcodes
2️⃣ Style it using CSS and make sure the stylesheet is linked in our theme/templates.
3️⃣ Use the shortcode inside our Markdown files (e.g., index.md).

@despiegk me and ehab did some research and took a look at astro and i think astro is complicated for marketingpeople to use. it would be easier for non tech people to edit website content if we just use the old way : zola + tailwind css + markdown shortcodes 1️⃣ Create the HTML shortcodes 2️⃣ Style it using CSS and make sure the stylesheet is linked in our theme/templates. 3️⃣ Use the shortcode inside our Markdown files (e.g., index.md).

mik-tf commented

2025-03-03 16:31:22 +00:00

As I understand, we want to create a hero astro feature so it is easy to create website and docs with astro, using the hero astro feature and basic markdown.

For e.g., see this basic cfg for docusaurus: https://git.ourworld.tf/tfgrid/docs_tfgrid4/src/branch/main/aibox/cfg

So we could go with astro starlight for docs, and astro wind for website. Wdyt? @sashaastiadi

As I understand, we want to create a hero astro feature so it is easy to create website and docs with astro, using the hero astro feature and basic markdown. For e.g., see this basic cfg for docusaurus: https://git.ourworld.tf/tfgrid/docs_tfgrid4/src/branch/main/aibox/cfg So we could go with astro starlight for docs, and astro wind for website. Wdyt? @sashaastiadi

Sign in to join this conversation.