Skip to content

Commit ba3e5dd

Browse files
Luiz-MicciMicci
Luiz-Micci
and
Micci
authored
docs: Deep README update (#44)
* 📝 docs(README): Deep readme update * Github Badge fix * 📝 Remove emojis from README.md --------- Co-authored-by: Micci <[email protected]>
1 parent 5f77bc1 commit ba3e5dd

File tree

1 file changed

+101
-59
lines changed

1 file changed

+101
-59
lines changed

‎README.md‎

Lines changed: 101 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -1,81 +1,123 @@
1+
# Templify
2+
3+
**Standardize and accelerate the creation of templates-based projects using definining placeholders across any kind of project**
4+
5+
Templify is a Maven plugin that helps you generate templates-based from a predefined project using a YAML-based configuration. It supports advanced transformations such as XPath-based replacement in XML files – ideal for managing complex project scaffolding and enforcing consistency.
6+
17
[![Build and Deploy](https://github.com/thoughtworks/templify/actions/workflows/gitAction.yml/badge.svg)](https://github.com/thoughtworks/templify/actions/workflows/gitAction.yml)
28

39
---
410

5-
# Templifly
11+
## What does it do?
612

7-
Templifly is a Maven plugin designed to simplify the process of managing and automating template-based configurations in your projects. By mapping key files—such as XML, JSON, YAML, Java code, or even plain text—Templifly allows you to define placeholders and automate their replacement in a centralized and flexible way.
13+
Templify automates the generation of templates by:
814

9-
Instead of manually editing repetitive elements across files, you can manage everything through a single configuration file. Placeholders are automatically replaced with the appropriate values during the build process, making your setup faster, more reliable, and less error-prone. This plugin supports structured data formats like XML and JSON and can handle custom elements in Java files, offering flexibility for unique project requirements.
15+
- Reading a YAML config file (`maven-templify.yml`)
16+
- Loading project files from a directory
17+
- Applying structured transformations (like XPath replacements in XML)
18+
- Outputting a complete, placeholders templates-based ready to integrate with your Backstage, Jinja and so on
1019

1120
---
1221

13-
## Plugin current status
14-
The plugin is currently in development and is ready for early-stage adoption and validation.
15-
Today, the plugin supports:
16-
* XML
17-
* YAML
18-
* JSON
19-
* Plain text
20-
* Java files and packages
22+
## Who is it for?
2123

24+
Templify is built for:
2225

23-
## Quickstart
26+
- **Base Platform teams** creating reusable service templates
27+
- **Developers** automating repetitive setup tasks
28+
- **Organizations** seeking consistent project standards and faster delivery
2429

25-
### Requirements
26-
The basic requirements to use the Templifly-templater plugin are as follows:
30+
---
2731

28-
* JDK11+
29-
* Apache Maven 3.9.1
32+
## How it works
3033

31-
## Getting Started
32-
To start using the plugin, you are going to need to adjust the configuration file.
33-
The configuration file is `maven-templifly.yml`. After the adjusment of the configurationfile, you will need to run the command below:
34+
You define:
3435

36+
- A **template folder** containing your base project
37+
- A **YAML config file** that describes:
38+
- Which files to transform
39+
- How to match content (XPath for XML)
40+
- What to replace
41+
42+
Templify will process the files and generate a project in a specified destination.
43+
44+
---
45+
46+
## 🧪 Example usage
47+
48+
### 1. Prepare your config file
49+
50+
`maven-templify.yml`:
51+
52+
```yaml
53+
steps:
54+
- kind: XmlHandler
55+
apiVersion: v1
56+
spec:
57+
- files:
58+
- pom.xml
59+
placeholders:
60+
- match: /project/groupId
61+
replace: templify.param.groupId
62+
- match: /project/artifactId
63+
replace: templify.test.replace.map.artifactId
64+
- match: /project/dependencies/dependency/scope[text()='test']
65+
replace: templify.replace.map.scopes
66+
- files:
67+
- xmls/generic_1.xml
68+
placeholders:
69+
- match: /note/heading
70+
replace: New Reminder
71+
- files:
72+
- xmls/complex/generic_2.xml
73+
placeholders:
74+
- match: /bookstore/book/author[text()='Kurt Cagle']
75+
replace: templify.kurtCagle
76+
- match: /bookstore/book/year[text()='2005']
77+
replace: templify.NewYear
3578
```
79+
80+
---
81+
82+
### 2. Run the plugin
83+
84+
```bash
3685
mvn com.thoughtworks.templify:templify:create
3786
```
3887

39-
### Usage of the configuration file.
40-
As mentioned, the plugin supports some file types and we are going to explain the configuration for each supported types.
41-
But first let understand the configuration file structure.
88+
-
89+
90+
## Template folder structure
4291

43-
#### Configuration file structure
44-
The configuration file is in a `Yaml` type and has the following structure:
4592
```
46-
settings
47-
└── placeholder
48-
| └── prefix
49-
| └── suffix
50-
steps
51-
└── - kind
52-
| └── apiVersion
53-
| └── spec
54-
| └── - files
55-
| └── placeholders
56-
| └── - match
57-
| └── replace
93+
94+
📁 target/template/
95+
├── pom.xml
96+
├── xmls/
97+
│ ├── generic_1.xml
98+
│ └── complex/generic_2.xml
99+
└── other project files...
58100
```
59-
#### 1. **settings**
60-
- **placeholder**: Configures how placeholders are identified within files.
61-
- **prefix**: Specifies the prefix marking the start of a placeholder.
62-
- **suffix**: Specifies the suffix marking the end of a placeholder.
63-
- This setup lets the plugin locate variables needing replacement in the template files and if it is not defined the default prefix and sufix at the placeholder will be `{{` and `}}`.
64-
#### 2. **steps**
65-
- A list of actions, with each item defining a specific configuration step.
66-
- **kind**: Identifies the type of action to perform at this step. Ex: XmlHandler, YmlHandler, JavaHandler...
67-
- **apiVersion**: Defines the API version used for executing this action. today we have only the `v1`
68-
- **spec**: Contains instructions for the step, including files and placeholders to be processed.
69-
- **files**: Lists the files and paths that will be processed for replacements. The path should be informed from the root of the project
70-
- **placeholders**: Specifies the replacement operations in each file.
71-
- **match**: The text or pattern the plugin will locate within the file.
72-
- **replace**: The text that will replace the `match`.
73-
74-
### Summary of How It Works
75-
This configuration allows the plugin to:
76-
- Identify variables with placeholders using the specified `prefix` and `suffix`.
77-
- Execute specific steps (`steps`) to replace values in designated files according to the `placeholders` rules in each step.
78-
79-
80-
### More Information
81-
For detailed documentation and advanced configuration options, please refer to our [Templifly Wiki](https://github.com/thoughtworks/Templify/wiki)
101+
102+
Templify will copy this structure to the `target/template` folder and apply the transformations defined in `maven-templify.yml`.
103+
104+
---
105+
106+
## What makes it powerful?
107+
108+
- 🎯 **XPath JSONPath, YAMLPath, JAva Procjects and Plain Text support** for precise targeting your project nodes
109+
- 🔄 **Batch transformations** across multiple files
110+
- 💼 **Custom parameter references** (e.g., `templify.param.groupId`)
111+
- 🧩 **Composable templates** for different types of services or modules
112+
113+
---
114+
115+
## Learn More
116+
117+
- [Templify Wiki](https://github.com/thoughtworks/templify/wiki)
118+
119+
--
120+
121+
## Contributing
122+
123+
Spotted a bug or have a new use case in mind? We welcome contributions, ideas, and questions. Open an [issue](https://github.com/thoughtworks/templify/issues) or submit a PR!

0 commit comments

Comments
 (0)