An Astro integration for rendering PlantUML diagrams in your markdown files. This integration automatically converts PlantUML code blocks into beautiful diagrams using the PlantUML server.
- 🌐 Starlight Demo (GitHub) - Full documentation site using Starlight theme
- 🌐 Plain Astro Demo (GitHub) - Simple Astro site with PlantUML examples
- 🎨 Automatic conversion of PlantUML code blocks to images
- ⚡ Fast rendering using PlantUML's server
- 🎯 Customizable server URL and timeout settings
- 🎭 Optional CSS classes for styling
- 🔧 Configurable language identifier for code blocks
- 🌐 Support for custom PlantUML servers
npx astro add astro-plantumlCheck out our demo sites to see various PlantUML diagrams in action!
- Add the integration to your
astro.config.mjs:
import { defineConfig } from 'astro/config';
import plantuml from 'astro-plantuml';
export default defineConfig({
integrations: [plantuml()],
});- Use PlantUML in your markdown files:
# My Documentation
Here's a sequence diagram:
```plantuml
@startuml
Alice -> Bob: Hello
Bob --> Alice: Hi there!
@endumlAnd here's a class diagram:
@startuml
class Car {
+String make
+String model
+int year
+start()
+stop()
+accelerate()
}
@endumlYou can also use different themes:
@startuml
!theme plain
class User {
+String name
+String email
+login()
+logout()
}
@enduml
## Configuration
You can configure the integration with the following options:
```js
plantuml({
// URL of the PlantUML server (default: 'http://www.plantuml.com/plantuml/png/')
serverUrl: 'https://your-custom-plantuml-server.com/plantuml/png/',
// Timeout for HTTP requests in milliseconds
timeout: 10000,
// Whether to add CSS classes to wrapper elements
addWrapperClasses: true,
// Language identifier in code blocks
language: 'plantuml'
})
By default, the integration uses the public PlantUML server. However, you can use your own PlantUML server by setting the serverUrl option. This is useful when you:
- Need better performance or reliability
- Want to avoid rate limits
- Need to use custom themes or styles
- Want to keep your diagrams private
Example using a custom server:
plantuml({
serverUrl: 'https://your-custom-plantuml-server.com/plantuml/png/',
// ... other options
})You can set up your own PlantUML server using:
- Docker:
docker run -d -p 8080:8080 plantuml/plantuml-server:jetty - Java: Run the PlantUML server JAR file
- Other deployment options as per PlantUML's documentation
When addWrapperClasses is enabled (default), the integration adds the following CSS classes:
plantuml-diagram: Wrapper around the diagramplantuml-img: The actual image element
You can style these in your CSS:
.plantuml-diagram {
margin: 2rem 0;
text-align: center;
}
.plantuml-img {
max-width: 100%;
height: auto;
border: 1px solid #eee;
border-radius: 4px;
}@startuml
participant User
participant Frontend
participant Backend
participant Database
User -> Frontend: Login Request
Frontend -> Backend: POST /api/login
Backend -> Database: Validate Credentials
Database --> Backend: User Data
Backend --> Frontend: JWT Token
Frontend --> User: Welcome Message
@enduml@startuml
class Animal {
+String name
+int age
+makeSound()
+move()
+eat()
}
class Dog {
+String breed
+bark()
+fetch()
}
class Cat {
+String color
+meow()
+climb()
}
Animal <|-- Dog
Animal <|-- Cat
@enduml@startuml
start
:User visits website;
if (Logged in?) then (yes)
:Show dashboard;
else (no)
:Show login form;
endif
:User interacts with site;
stop
@endumlIf there's an error generating a diagram, the integration will:
- Display an error message
- Keep the original code block for reference
- Add the
plantuml-errorclass to the error container
- 🐛 Fixed PlantUML rendering by switching from rehype to remark plugin
- 🚀 Plugin now processes code blocks before syntax highlighting
- 🔧 Fixed encoding issue with PlantUML server (using deflateRawSync instead of deflateSync)
- 🧹 Removed deprecated rehype plugin
- Remark plugin runs before Shiki to prevent language warnings
- 🎉 Initial release
- ✨ Basic PlantUML rendering functionality
- 🎨 Configurable options (serverUrl, timeout, addWrapperClasses, language)
- 📚 Support for all PlantUML diagram types
- 🔧 Error handling with fallback to original code block
- 🚀 Initial development version
- ⚡ Core integration with Astro
- 🎯 Basic PlantUML to image conversion
- Ensure you have npm publish permissions for the
astro-plantumlpackage - Make sure you're logged in to npm:
npm login - All tests should pass and the package should build successfully
-
Update Version
# For patch release (bug fixes): 0.1.2 -> 0.1.3 npm version patch # For minor release (new features): 0.1.2 -> 0.2.0 npm version minor # For major release (breaking changes): 0.1.2 -> 1.0.0 npm version major
-
Build the Package
npm run build
-
Test Locally (optional but recommended)
# Create a tarball npm pack # Test in another project npm install /path/to/astro-plantuml-0.1.3.tgz
-
Update Changelog
- Add new version entry to the Changelog section above
- Document all changes, fixes, and new features
- Use semantic versioning and date format
-
Commit Changes
git add . git commit -m "Release v0.1.3" git push origin main
-
Create Git Tag
git tag v0.1.3 git push origin v0.1.3
-
Publish to npm
npm publish
-
Verify Publication
- Check npm page: https://www.npmjs.com/package/astro-plantuml
- Test installation:
npm install astro-plantuml@latest
- Update demo sites with the new version
- Create a GitHub release with release notes
- Announce in relevant channels (Discord, Twitter, etc.)
Visit our demo sites to see:
- Sequence diagrams
- Class diagrams
- Activity diagrams
- State diagrams
- Component diagrams
- Mind maps
- Gantt charts
MIT