• 

  Main Image

Mapscript – From Markdown to Mindmaps

Inspiration

The idea for Mapscript was born from a simple frustration:
Every time I wanted to visualize a roadmap, process, or learning guide, I had to design it from scratch — even when I already had the content written as markdown or plain text.

As someone passionate about accessibility, education, and rapid communication, I asked:

“What if we could turn structured text like markdown — or even a simple user prompt — into a styled, connected roadmap inside Adobe Express?”

This idea aligns with the mission of my broader initiative Coders Beyond Borders: to empower creators, educators, and nonprofits through inclusive, open, and human-centered technology.

What I Learned

This was my first time developing for Adobe Express Add-ons, and here’s what I learned:

• How to build and package Express Add-ons using @adobe/ccweb-add-on-scripts
• How to interact with the Express Document SDK to create nodes, style text, and manipulate document structure
• How to parse Markdown into an AST and extract structured roadmap steps
• How to dynamically render Express components like rectangles, text, and connectors with layout logic
• The nuances of working inside the sandboxed Adobe Express environment, including limits and powerful styling capabilities

How I Built It

The project is built using the Adobe Express Add-ons platform. Here's how everything works step-by-step:

1. User uploads a markdown file
   or writes a prompt to describe what they want (like "How to ride a bicycle").

2. The markdown is parsed
   We use a custom markdown-parser.js file to break it into parts like headings, steps, and bullet points.

3. We extract the roadmap steps
   A function reads the markdown and finds the title and the steps under a "Steps" section.

4. We format the content for Adobe Express
   Using adobe-express-formatter.js, we style the text and plan the layout of each step box and bullet list.

5. We send the steps to the Express document
   The add-on uses sandboxProxy.renderRoadmapFromParsedMarkdown() to create:

   • A big title at the top
   • Rectangle boxes for each step
   • Bullet points under each step
   • Lines connecting the steps

6. The roadmap is created visually inside Adobe Express!

Everything is dynamic — box sizes adjust automatically, and the layout stays neat and centered.

Key Tools & Tech:

• Adobe Express Add-ons SDK
• express-document-sdk for node creation & styling
• markdown-to-ast to extract structured information
• Spectrum Web Components (sp-button, sp-dropzone, sp-textfield)
• Vanilla JavaScript for file handling & UI events
• Custom dynamic layout logic for auto-box sizing & alignment

Challenges I Faced

1. Limited documentation & evolving APIs:
   Many properties and methods like setPositionInParent() or applyCharacterStyles() required trial and error, since docs weren’t always up to date.

2. Dynamic layout calculation:
   Dynamically sizing and aligning text inside boxes — while keeping connectors clean — required careful offset math and experimentation.

3. Sandbox constraints:
   Understanding what works inside document-sandbox vs the regular web runtime took time, especially when dealing with assets, events, and cross-context APIs.

4. AI integration (next phase):
   While the prompt-input is ready, integrating a proper backend for AI markdown generation is planned for the post-hackathon roadmap.

What’s Next?

• Integrate AI using OpenAI or Claude API to generate markdown from natural prompts
• Support branching mindmaps, alternate layouts, and templates
• Publish on Adobe Express Add-ons marketplace
• Collaborate with nonprofits and educators to co-create public templates

Closing Thought

Mapscript is more than a hackathon project.
It’s a small step toward helping everyone tell stories, teach concepts, and build structured visual thinking — effortlessly.

Let’s go beyond borders, one roadmap at a time.

Built With

• adobe-express-add-ons-sdk
• ccweb-add-on-scripts
• document-sandbox
• express-document-sdk
• javascript
• markdown
• openai-gpt-api-(planned)
• spectrum-web-components
• typescript