updated readme
This commit is contained in:
parent
c01c90d4ce
commit
83413b8b1f
@ -1,5 +1,5 @@
|
||||
# The URL the site will be built for
|
||||
base_url = "https://zola-template.staging.grid.tf/"
|
||||
base_url = "https://zola-template.staging.grid.tf"
|
||||
# Change this to your own URL! Please note this variable **must** be uncommented.
|
||||
|
||||
title = "Template"
|
||||
|
||||
211
readme.md
211
readme.md
@ -1,101 +1,188 @@
|
||||
# TF9 Website
|
||||
# Zola Tailwind Template
|
||||
|
||||
Welcome to the official repository for the **TF9** website, accessible at [www.tf9.io](https://www.tf9.io). This site serves as the digital front for TF9, providing information, resources, and access to the latest developments within the ThreeFold community.
|
||||
A modern static site template built with [Zola](https://www.getzola.org/) static site generator and [Tailwind CSS](https://tailwindcss.com/).
|
||||
|
||||
## Project Overview
|
||||
## Features
|
||||
|
||||
The TF9 website is built using modern, efficient web technologies to ensure a seamless user experience. The stack includes:
|
||||
- Fast and lightweight static site generation with Zola
|
||||
- Modern responsive design with Tailwind CSS
|
||||
- Reusable components via Zola shortcodes
|
||||
- Dark mode support
|
||||
- Blog section with Markdown content
|
||||
- Team member profiles
|
||||
|
||||
- **Zola**: A fast, static site generator designed for simplicity and performance.
|
||||
- **Tailwind CSS**: A utility-first CSS framework for rapid UI development.
|
||||
- **JavaScript**: Enhancing interactivity and functionality on the website.
|
||||
- **Markdown**: Used for writing content in a simple and readable format, which Zola converts into HTML.
|
||||
- **HTML**: The backbone of the web pages, structuring the content and defining the layout of the website.
|
||||
## Prerequisites
|
||||
|
||||
Before you begin, ensure you have the following installed:
|
||||
|
||||
## Environments
|
||||
- [Zola](https://www.getzola.org/documentation/getting-started/installation/) (v0.15.0 or later)
|
||||
- [Node.js](https://nodejs.org/) (v14.0.0 or later)
|
||||
- npm (usually comes with Node.js)
|
||||
|
||||
The TF9 website is deployed across two environments:
|
||||
### Installing Zola
|
||||
|
||||
- **Production**:
|
||||
- **Branch**: `main`
|
||||
- **URL**: [www.tf9.io](https://www.tf9.io)
|
||||
Follow the instructions on the [Zola installation page](https://www.getzola.org/documentation/getting-started/installation/) for your operating system.
|
||||
|
||||
- **Development**:
|
||||
- **Branch**: `dev`
|
||||
- **URL**: [www2.tf9.io](https://www2.tf9.io)
|
||||
### Installing Node.js and npm
|
||||
|
||||
## Installation
|
||||
Download and install from the [Node.js website](https://nodejs.org/).
|
||||
|
||||
To get started with the development environment, ensure that you have the following installed on your machine:
|
||||
## Running Locally
|
||||
|
||||
1. **Zola**: [Installation Guide](https://www.getzola.org/documentation/getting-started/installation/)
|
||||
2. **Tailwind CSS**: [Installation Guide](https://tailwindcss.com/docs/installation)
|
||||
3. **Node.js & npm**: Required for managing JavaScript dependencies.
|
||||
To run the site locally for development:
|
||||
|
||||
|
||||
## Getting Started
|
||||
|
||||
Once these dependencies are installed, you can clone this repository and navigate into the project directory:
|
||||
1. Clone this repository or download and extract the ZIP file
|
||||
2. Navigate to the project directory in your terminal
|
||||
3. Run the start script:
|
||||
|
||||
```bash
|
||||
git clone https://git.ourworld.tf/tfcoop/www_tf9_new
|
||||
cd www_tf9_new
|
||||
# On Linux/macOS
|
||||
./start.sh
|
||||
|
||||
# On Windows
|
||||
# Either use Git Bash to run ./start.sh
|
||||
# Or run these commands manually:
|
||||
npm install
|
||||
npx tailwindcss -i ./static/css/main.css -o ./static/css/output.css --watch & zola serve
|
||||
```
|
||||
|
||||
### Reviewing New Website Changes Locally
|
||||
The start script will:
|
||||
- Install Tailwind CSS and dependencies if not already installed
|
||||
- Start the Tailwind CSS watcher to compile CSS changes
|
||||
- Start the Zola development server
|
||||
|
||||
#### Access the Terminal
|
||||
Within your code editor, open the terminal or command line interface. Make sure you are in the root directory of your website project in the terminal.
|
||||
Once running, you can access the site at [http://127.0.0.1:1111](http://127.0.0.1:1111)
|
||||
|
||||
#### Run the Build Script:
|
||||
Type **./build.sh** in the terminal and press Enter. This script is responsible for building or compiling your website code and assets.
|
||||
## Building for Production
|
||||
|
||||
#### Run the Start Script:
|
||||
After the build process is complete, type **./start.sh** in the terminal and press Enter. This script typically starts a local development server.
|
||||
To build the site for production:
|
||||
|
||||
Wait for the Localhost URL: The start script will initiate a local development server, and it will display a localhost URL, such as **http://localhost:xxxx**, where xxxx is a port number. Wait for this URL to be generated.
|
||||
```bash
|
||||
# On Linux/macOS
|
||||
./build.sh
|
||||
|
||||
### Open the URL in Your Browser
|
||||
Once the localhost URL is generated, open your web browser and enter the provided URL (e.g., http://localhost:xxxx). This will display your website locally, allowing you to review the changes you made.
|
||||
# On Windows
|
||||
# Either use Git Bash to run ./build.sh
|
||||
# Or run these commands manually:
|
||||
npm install
|
||||
npx tailwindcss -i ./static/css/main.css -o ./static/css/output.css --minify
|
||||
zola build
|
||||
```
|
||||
|
||||
## Contributing
|
||||
The build script will:
|
||||
- Install Tailwind CSS and dependencies if not already installed
|
||||
- Build and minify the Tailwind CSS
|
||||
- Build the Zola site for production
|
||||
|
||||
We welcome contributions from the community! To contribute:
|
||||
The built site will be in the `public` directory, which you can deploy to any static hosting service.
|
||||
|
||||
Create a new branch (git checkout -b feature/your-feature-name).
|
||||
Make your changes and commit them (git commit -m 'Add new feature').
|
||||
Push to the branch (git push origin feature/your-feature-name).
|
||||
Open a Pull Request.
|
||||
## Using Shortcodes
|
||||
|
||||
## Issues and Suggestions
|
||||
Shortcodes are reusable components that can be included in your Markdown content. This template includes several pre-built shortcodes:
|
||||
|
||||
We welcome feedback, bug reports, and feature requests to help improve the TF9 website. If you encounter any issues or have suggestions, please follow the steps below:
|
||||
### Hero Section
|
||||
|
||||
1. Go to the **TF Web Presence project** board on Gitea: [Project](https://git.ourworld.tf/tfgrid/circle_web_presence/projects/35)
|
||||
2. Click on the "New Issue" button.
|
||||
3. Provide a clear title and detailed description of the issue or suggestion.
|
||||
4. Add relevant labels, milestones, or assignees if applicable.
|
||||
5. Submit the issue.
|
||||
```markdown
|
||||
{{ hero(title="Welcome", subtitle="A modern website built with Zola and Tailwind CSS", button_text="Learn More", button_link="/about") }}
|
||||
```
|
||||
|
||||
Our team will review and address your submission as soon as possible.
|
||||
### Alternative Hero Styles
|
||||
|
||||
Thank you for helping us improve TF9!
|
||||
```markdown
|
||||
{{ hero2(title="Welcome", subtitle="A modern website", button_text="Learn More", button_link="/about") }}
|
||||
|
||||
{{ hero3(title="Welcome", subtitle="A modern website", button_text="Learn More", button_link="/about") }}
|
||||
```
|
||||
|
||||
## Administrators
|
||||
[ThreeFold's Web Presence Team](https://git.ourworld.tf/tfgrid/circle_web_presence/)
|
||||
### Feature Card
|
||||
|
||||
## Website Maintenance
|
||||
```markdown
|
||||
{{ feature_card(title="Fast and Lightweight", description="Zola generates static HTML files that load quickly", icon="⚡") }}
|
||||
```
|
||||
|
||||
|
||||
### Call-to-Action (CTA)
|
||||
|
||||
It is highly important to follow this procedure to contribute to the website content. <br>
|
||||
__WARNING__: DO NOT commit straight into __master__ / __development__ branch.
|
||||
```markdown
|
||||
{{ cta(title="Ready to Get Started?", description="Create your own beautiful website with Zola and Tailwind CSS today.", button_text="View Blog", button_link="/blog") }}
|
||||
```
|
||||
|
||||
## Build Notes
|
||||
For more detailed documentation on available shortcodes and their parameters, see the [shortcodes.md](content/shortcodes.md) file.
|
||||
|
||||
There was an issue with v4.0.0 of tailwind. For now we build the website with v3.4.17.
|
||||
## Creating Custom Shortcodes
|
||||
|
||||
References: https://github.com/threefoldtech/tf_operations/issues/3091
|
||||
To create a new shortcode:
|
||||
|
||||
1. Create a new HTML file in the `templates/shortcodes/` directory, e.g., `templates/shortcodes/my_shortcode.html`
|
||||
2. Write your shortcode template using Zola's template syntax (based on Tera templates)
|
||||
|
||||
Here's an example of a simple shortcode template:
|
||||
|
||||
```html
|
||||
{% set title = title | default(value="Default Title") %}
|
||||
{% set description = description | default(value="") %}
|
||||
|
||||
<div class="bg-white p-6 rounded-lg shadow-md">
|
||||
<h3 class="text-xl font-bold">{{ title }}</h3>
|
||||
{% if description %}
|
||||
<p class="mt-2 text-gray-600">{{ description }}</p>
|
||||
{% endif %}
|
||||
{% if caller %}
|
||||
<div class="mt-4">{{ caller() }}</div>
|
||||
{% endif %}
|
||||
</div>
|
||||
```
|
||||
|
||||
### Parameters
|
||||
|
||||
Define parameters at the top of your shortcode file using the `{% set parameter = parameter | default(value="default_value") %}` syntax.
|
||||
|
||||
### Nested Content
|
||||
|
||||
To allow nested content inside your shortcode, include the `{% if caller %}{{ caller() }}{% endif %}` block.
|
||||
|
||||
### Using Your New Shortcode
|
||||
|
||||
In your Markdown content:
|
||||
|
||||
```markdown
|
||||
{{ my_shortcode(title="Custom Component", description="This is my custom shortcode") }}
|
||||
```
|
||||
|
||||
With nested content:
|
||||
|
||||
```markdown
|
||||
{% call my_shortcode(title="With Nested Content") %}
|
||||
This content will appear inside the shortcode.
|
||||
|
||||
You can include **Markdown** here.
|
||||
{% endcall %}
|
||||
```
|
||||
|
||||
## Customization
|
||||
|
||||
### Site Configuration
|
||||
|
||||
Edit the `config.toml` file to change site-wide settings:
|
||||
|
||||
```toml
|
||||
base_url = "https://your-domain.com"
|
||||
title = "Your Site Title"
|
||||
description = "Your site description"
|
||||
```
|
||||
|
||||
### Styling
|
||||
|
||||
- Main CSS file: `static/css/index.css`
|
||||
- Tailwind configuration: `tailwind.config.js`
|
||||
- SASS files (if used): `sass/` directory
|
||||
|
||||
## Deployment
|
||||
|
||||
After building the site, deploy the contents of the `public` directory to any static hosting service like:
|
||||
|
||||
- [Netlify](https://www.netlify.com/)
|
||||
- [Vercel](https://vercel.com/)
|
||||
- [GitHub Pages](https://pages.github.com/)
|
||||
- [Cloudflare Pages](https://pages.cloudflare.com/)
|
||||
|
||||
Most of these services can be configured to automatically run your build script when you push to your repository.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user