Skip to content

Commit 445f332

Browse files
ChristianHohlfeldChristianHohlfeld
authored
Update README.md
1 parent b42ad1a commit 445f332

File tree

1 file changed

+50
-210
lines changed

1 file changed

+50
-210
lines changed

‎README.md‎

Lines changed: 50 additions & 210 deletions
Original file line numberDiff line numberDiff line change
@@ -1,249 +1,89 @@
1-
# ✍️ MiniTemplate - Simple Template Engine
2-
3-
This guide will walk you through setting up a MiniTemplate project, adding components, templates, and generating the static `index.html` file as result.
4-
5-
## Directory Structure Overview
6-
7-
```console
8-
.
9-
├── run_create_project.sh # create a new project
10-
├── components
11-
│ ├── converted # Converted components ready for use in the project
12-
│ ├── default # Default components provided by MiniTemplate
13-
│ ├── custom # Custom user-defined components
14-
│ ├── source # Source components to be converted
15-
├── public # Final static site can be served from here
16-
├── scripts # Utility scripts for generating the site
17-
├── templates # HTML template for the project
18-
├── tests # Test scripts to validate MiniTemplate functionality
19-
```
20-
21-
## Step 1: Setting Up Your Project
22-
23-
### Clone the repository
241

25-
```console
26-
git clone https://github.com/nostack-dev/minitemplate.git
27-
cd minitemplate
28-
```
2+
# MiniTemplate
293

30-
Ensure all the files and directories listed in the directory structure are present before proceeding.
4+
MiniTemplate is a lightweight, efficient template engine tailored for static web applications. It simplifies component reuse and ensures design consistency across projects. MiniTemplate seamlessly integrates with Tailwind CSS and DaisyUI to accelerate UI development.
315

32-
### Run `run_create_project.sh`
6+
## Project Structure
337

34-
This script will create a new project directory with default components and templates.
8+
The project follows a simple, organized folder structure:
359

36-
```console
37-
chmod +x run_create_project.sh && ./run_create_project.sh
3810
```
39-
40-
You will be prompted to provide a name for your project. Once done, the script will generate a new project directory under `projects/` with the necessary components and templates copied over.
41-
42-
When prompted for a project name, use:
43-
44-
```console
45-
myproject
11+
/components # Reusable UI components
12+
/scripts # Automation scripts for managing project workflows
13+
/templates # Core HTML templates for project scaffolding
14+
/tests # Automated tests to verify components and scripts
4615
```
4716

48-
Then navigate to your created project:
49-
50-
```console
51-
cd ./projects/myproject
52-
```
17+
## Scripts Overview
5318

54-
This will create a new folder `projects/myproject` with the default components and scripts inside.
19+
### `run_create_project.sh`
5520

56-
Default components are automatically added during project creation. If needed, you can override them using the `run_add.sh defaults` command, but this is not the main focus.
21+
This script streamlines the creation of new projects by generating the necessary folders and files based on a predefined template. You can specify various parameters to customize the setup.
5722

58-
## Step 2: Adding Components to Your Project
23+
**Parameters:**
24+
- `--project-name`: The name of your new project.
25+
- `--template`: Choose a template to base your project on (e.g., `default`, `blog`, `ecommerce`).
5926

60-
MiniTemplate allows you to easily add components to your project using the `run_add.sh` script.
27+
**Usage Example:**
6128

62-
### List Available Components
63-
64-
To list all available components, run the `run_add.sh` script without any arguments inside your project directory:
65-
66-
```console
67-
./run_add.sh
29+
```bash
30+
./scripts/run_create_project.sh --project-name my-awesome-app --template ecommerce
6831
```
6932

70-
You will see a list of components from `components/default`, `components/custom`, and `components/converted`.
71-
72-
### Add Specific Components
73-
74-
To add a specific component to your project, pass the component name as an argument to `run_add.sh`:
75-
76-
```console
77-
./run_add.sh button
78-
```
79-
80-
This will copy the `button.html` component into your project directory.
81-
82-
After adding a component, you can embed it in any template or component file using the `{{component_name}}` syntax. For example, to use the button component, add `{{button}}` to your template file.
83-
84-
## Step 3: Adding Template Variables and Generating the Static Site
33+
### `run_add.sh`
8534

86-
Once you have all the necessary components in place, you can integrate them into your templates using the `{{component_name}}` syntax. This allows for nesting components within templates or even within other components.
35+
Use this script to add new components (like UI elements) into your project dynamically.
8736

88-
For example, to include a `button` component within a template, simply add `{{button}}` to the desired location in your template file.
37+
**Parameters:**
38+
- `--component`: The name of the component to be added (e.g., `navbar`, `footer`).
39+
- `--project`: The project directory where the component will be placed.
8940

90-
### Generate the Static Site
41+
**Usage Example:**
9142

92-
From your project directory, run:
93-
94-
```console
95-
./run_generate_site.sh
43+
```bash
44+
./scripts/run_add.sh --component navbar --project my-awesome-app
9645
```
9746

98-
The script processes the main template (`template_default.html`), replacing placeholders (e.g., `{{header_default}}`) with the appropriate component files. The resulting `index.html` can be served directly on any static web host, such as GitHub Pages.
99-
100-
After generating the site, you can copy the `index.html` file to the `public` directory:
47+
## Testing and Quality Assurance
10148

102-
```console
103-
cp index.html ../../public/
104-
```
105-
106-
This will allow the static site to be served from the `public` directory if desired.
107-
108-
### Placeholders
109-
Any template file or component HTML file can include other components using the `{{component}}` syntax. When you run `run_generate_site.sh` from your project folder, these placeholders are replaced by the actual component contents.
110-
111-
### Example: Using Template Variables
112-
113-
Here is an example of how `{{}}` placeholders are used within a template file (or any other Component):
114-
115-
```html
116-
<!DOCTYPE html>
117-
<html lang="en">
118-
<head>
119-
<meta charset="UTF-8">
120-
<meta name="viewport" content="width=device-width, initial-scale=1.0">
121-
<title>My Project</title>
122-
</head>
123-
<body>
124-
{{header_default}}
125-
<main>
126-
<h1>Welcome to My Project</h1>
127-
{{button}}
128-
</main>
129-
{{footer_default}}
130-
</body>
131-
</html>
132-
```
49+
The `/tests` directory contains automated tests designed to ensure that all project components and scripts function as expected. These tests validate everything from component integration to script execution.
13350

134-
In this example, the `{{header_default}}`, `{{button}}`, and `{{footer_default}}` placeholders are replaced with their respective component contents during the generation process.
51+
### Running Tests
13552

136-
## Step 4: Testing the Setup
53+
To run the entire suite of tests, simply navigate to the `tests` directory and execute:
13754

138-
You can run a suite of tests to ensure that your setup is working as expected.
139-
140-
### Run the Tests
141-
142-
Navigate to the `tests` directory, then run:
143-
144-
```console
145-
cd ./tests && ./run_tests.sh
55+
```bash
56+
bash run_tests.sh
14657
```
14758

148-
This will execute the test suite found in the `tests/` directory and validate your project’s setup, components, and templates.
149-
150-
Example output:
59+
## Workflow Overview
15160

152-
```console
153-
### Test Start
154-
---------------------------------
61+
1. **Project Initialization**: Create a new project with `run_create_project.sh`.
62+
2. **Component Addition**: Dynamically add components using `run_add.sh`.
63+
3. **Customization**: Adjust your components or templates to fit your needs.
64+
4. **Testing**: Run the tests to verify that everything works as intended.
15565

156-
## Running Tests
66+
## Dependencies
15767

158-
✔ Test passed: ./test_addcomponent.sh
159-
✔ Test passed: ./test_component_ids.sh
160-
✔ Test passed: ./test_component_references.sh
161-
✔ Test passed: ./test_index_served.sh
162-
✔ Test passed: ./test_print.sh
163-
✔ Test passed: ./test_template_generation.sh
68+
To ensure smooth operation, the following dependencies must be installed:
16469

165-
### Test Summary
166-
---------------------------------
167-
✔ All tests passed!
168-
---------------------------------
70+
- **Node.js**: Required for managing frontend libraries like Tailwind CSS and DaisyUI.
71+
- **Tailwind CSS**: For styling components and templates.
72+
- **DaisyUI**: For pre-built UI components.
73+
- **Bash**: Used to execute the provided shell scripts.
16974

170-
Total Tests Passed: 6
171-
Total Tests Failed: 0
75+
## Getting Started
17276

173-
All tests finished.
174-
```
175-
176-
If all tests pass, you’ll receive a success message. If any tests fail, check the logs to identify the issue.
177-
178-
## Additional Step: Converting Source Components (Optional)
179-
180-
MiniTemplate allows you to transform raw components from `components/source`, which are basic DaisyUI HTML-files, into usable MiniTemplate components in `components/converted`. See all daisyUI-Components [here]([url](https://daisyui.com/components/button/)).
181-
182-
### Convert Components
77+
1. Clone the repository to your local machine:
18378

184-
Navigate to the `scripts` directory and use the `convert_components.sh` script to convert all raw components:
185-
186-
```console
187-
cd ./scripts && ./convert_components.sh
188-
```
189-
190-
This will read all HTML files in the `source` directory and convert them into self-contained components, which will be placed in the `converted` directory.
191-
192-
### Structure Comparison: Source vs Converted
193-
194-
- **Source Component Example (Basic DaisyUI HTML):**
195-
196-
```html
197-
<div class="alert">
198-
<span>Alert message here!</span>
199-
</div>
200-
```
201-
202-
- **Converted Component Example (MiniTemplate Component):**
203-
204-
```html
205-
<div id="alert_component">
206-
<div class="alert">
207-
<span>Alert message here!</span>
208-
</div>
209-
<script>
210-
(function() {
211-
// Component-specific JavaScript
212-
})();
213-
</script>
214-
</div>
215-
```
216-
217-
The converted components are self-contained and modular, allowing for easy reuse and consistent styling throughout your project. Each component includes a JavaScript block for additional behavior, making them more powerful compared to the basic DaisyUI HTML.
218-
219-
## MiniTemplate-Components Don’t Look Special or New—What Sets Them Apart?
220-
221-
At first glance, MiniTemplate components may seem like standard HTML, but their design offers distinct advantages:
222-
223-
```html
224-
<div id="alert_component"> <!-- Auto-generated ID -->
225-
<div class="alert"> <!-- Collision-free DaisyUI style-classes -->
226-
<span>Alert message here!</span>
227-
</div>
228-
<script>
229-
(function() { // Isolation of JavaScript using an IIFE
230-
let isOpen = true; // Local state variable for alert status
231-
// Component-specific JavaScript
232-
if (isOpen) {
233-
console.log("Alert is open");
234-
}
235-
})();
236-
</script>
237-
</div>
79+
```bash
80+
git clone https://github.com/nostack-dev/minitemplate.git
23881
```
23982

240-
- **Auto-Generated Unique ID:** Ensures each component is uniquely identifiable, preventing duplication.
241-
- **Collision-Free DaisyUI Styles:** Inline Tailwind CSS ensures that styles remain modular and do not interfere with others.
242-
- **Isolation of JavaScript:** Uses an immediately invoked function expression (IIFE) to prevent conflicts and enhance reliability.
243-
- **Local State Management:** Local state variables, like `isOpen`, can be utilized to manage component behavior within the function.
83+
2. Install any necessary dependencies by following the instructions in the `scripts` folder.
84+
3. Use the provided scripts to quickly set up and manage your project.
24485

245-
This combination results in a powerful, scalable approach to web development without adding unnecessary complexity, along with the option to integrate state management tools.
86+
---
24687

247-
Refer to [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to contribute and see [LICENSE](LICENSE) for licensing information.
88+
Enjoy building scalable and reusable web applications with **MiniTemplate**. Feel free to customize components and templates to fit your specific needs.
24889

249-
Thanks to [TailwindCSS](https://tailwindcss.com) and [daisyUI](https://daisyui.com/) for their great work.

0 commit comments

Comments
 (0)