Show HN: I’m building open-source headless CMS for technical content (vrite.io)
Whether that was a programming blog post or documentation, I always had to move back an forth between different editors, and sometimes even other apps for content management and the actual content publication. A lot of copy-pasting, and wasted time.
Based on this experience I decided to try and build a tool that could provide a good experience for this kind of content from writing to publishing. This (I call it Vrite) ended up being essentially a headless CMS, but optimized for technical content and a pretty unique one overall, I'd say.
I tried to combine what can be seen as 3 separate products into one: - WYSIWYG editor (with the addition of code-specific tooling like code editor or formatter) - Kanban dashboard (inspired by my experience of tools like Trello used in larger technical content teams to manage content production process) - The actual headless CMS (content delivery via API, integrations, etc.)
Most recently I decided to open-source it and see if there's any interest in such a tool. Right now the primary focus was my personal use-case (kind-of "promotional" technical writing seen in programming and start-up blogs), but I think, with more customization, something like this could extend to the documentation space and make writing and managing docs a lot easier.
Let me know what do you think about this.
53 comments
[ 3.0 ms ] story [ 118 ms ] threadEmail: hello@vrite.io
Password: Hello_2023
Please keep it safe and sane there :) The account will be reset every few hours.
You'll likely also want to read the usage guide before jumping in: https://docs.vrite.io/getting-started
Yeah, that sucks, it's much easier when you can do everything in VSCode/emacs/vim and don't have to leave your dev environment to write about what you're developing…
> WYSIWYG editor (with the addition of code-specific tooling like code editor or formatter)
…wait, what?
> Kanban dashboard (inspired by my experience of tools like Trello used in larger technical content teams to manage content production process)
But if I'm a lone dev, I have a personal kanban already to cover other things that aren't technical writing, and if I'm in a content team I have a full-blown kanban tool that handles multi-platform publishing. That often includes non-text content, so I wouldn't want to trade that tool for vrite either.
> The actual headless CMS (content delivery via API, integrations, etc.)
If there is to be any point to this, it better have really good integrations into existing documentation solutions.
Yet vrite's own technical documentation ist just outsourced to swagger's online service?
And it's not even good documentation: No description of possible errors, very little to no end point description, no description of what parameters do (or sometimes even are), … I don't think this is a good example for what the future of documentation should be.
I'm still trying to understand this product, but it looks like this might be it's best 'feature'. For example writing all your technical Blog posts in `vrite` instance, maybe have a backlog of them managed through the kanban board, and then be able to publish them directly to Medium for example, or codecademy etc.
Not particularly useful to me, but I will play around with local deploy and see if im missing something else.
In basically all technical marketing teams I've worked in, things weren't as automated as you might think. Kanban was only there to manage content production stages, while the actual content was to be written in the Dropbox Paper, Notion, GDocs, etc. just to be able to collaborate and go through the review process. In the end the content had to be copy-pasted to WordPress, Ghost, etc. in an entirely manual process with many formatting issues happening in the process.
In environment you're describing Vrite would indeed be a much "harder sell". Making users move to new tool is difficult in general. That said, with proper integrations and import tools, Vrite could be an "incrementally-adoptable" CMS, that you can transition to at your own pace.
I struggle to see what makes this a "technical content" CMS then, rather than just a generic marketing CMS.
For a generic marketing CMS aimed at marketers, the feature set makes a bit more sense. But for actual technical staff, all of these design decisions just break whatever flow the users might've had and add very little.
- Blogging/Developer marketing content - basically all the technical blogs you see & read; Devs run personal ones for portfolio and learning, while companies to attract potential employees or sell their product (if developers are the target audience). It's the space I've worked in the most and to which Vrite was (and still is) initially addressed to.
- General documentation - all the internal/external documentation that contains usage guides, covers important concepts, etc. Basically mostly text with elements of code. I think this is the most popular use-case of the three. Vrite could handle these but it would require support for custom content (docs often embed demos, display custom notes, etc.) and integration with Git (where most of this documentation often lives).
- Code & API documentation - what I think many in this thread had in mind in regards to technical content. This is mostly code, little text and usually highly automated (not just with publishing integrations, but in direct connection with the documented codebase). This is definitely something Vrite isn't designed to do and likely couldn't do no matter the features or customizations added. There are other tools for that.
Looking back, labeling Vrite as a "CMS for technical/developer marketing" might have made it more clear what the product's goals are.
Still, I got a lot of valuable feedback from this thread that I likely wouldn't get with a perfect headline, which I'm greatful for. I'm looking to put it towards improving the "CMS for technical/developer marketing" part and creating a versitile-enough tool for handling "General documentation".
Technical writing for example is very regularly done by non technical people who are very astute with processes, steps, input and output parameters. Kind of like a power user who can also simplify and explain.
Writing things only for a personal kanban or notebook makes it harder to invite, request or actively have some collaboration. I’m increasingly using the kanban in gitlab for this reason - there are decent enough mobile apps, and it’s ready and actionable.
While true, the tides are turning a bit here, at least for software technical writers. It's not uncommon to have a docs-as-code documentation toolchain where you're hosting all your docs in GitHub and serving them via static site. And most of the technical writers using these toolchains have no formal background in CS or previous programming know-how—myself included.
Back in the day I earned an English degree and now I'm managing PRs, generating OpenAPI files, and building out CSS/React to customize our docs site :P
Two things I couldn't really sort out from your docs or the site:
1. Is there support for uploading images? How is that handled?
2. Is there support for "table" data. An example: I'd like to have my headless CMS keep a list of conferences with fields for start_date, end_date and other attributes and then reference that in my site.
Thanks!
hugo, jekyll and most static blogs are "headless" CMSs. This is very explicitly setting itself apart from those by HAVING a "head".
"I tried to combine what can be seen as 3 separate products into one: - WYSIWYG editor (with the addition of code-specific tooling like code editor or formatter) - Kanban dashboard (inspired by my experience of tools like Trello used in larger technical content teams to manage content production process) - The actual headless CMS (content delivery via API, integrations, etc.)"
Read the last part.
your definition makes sense to me, but since this has a GUI it doesn't fall into that definition.
It can be hard to visualize so people may ask what could this look like?
From there a headless cms can use the api to render the data as a site. It can be static, or dynamic.
Like... i feel like i'm not understanding something obvious. I get the idea of an API only server. I've written many. BUT by shipping a GUI (as part of it or separately) and then touting the features of that gui for managing the CMS they're no longer talking about a "headless" thing. They're talking about a GUI that may talk to a "headless" cms but the entire point of the GUI is to get around the "headless" part.
It’s a starting point to both see what’s possible, and also a way to maybe have some boiler plate to experiment with right away to help users start using the api by example of usage not just by a call but in a front end.
I appreciate what you’re saying, got me it’s like finding an app and then wondering if it has an api. Both are useful
I recently started doing a project in this area too, it's tempting but there are a lot of push back from developers to change their habits (and markdown).
Anecdotally I also tried to integrate Monaco with TipTap, you did it way better than me, well played!
Also, yeah - integrating Monaco wasn't easy. Took me a while to get it right.
If you self-host, can you use it flat-file or does it require a database? If I have my content in Markdown files in a repo, where does Vrite fit in?
Why is there no search on https://docs.vrite.io/? Or am I just missing it?
That's going to be an obstacle for a lot of docs, support, and to a lesser extent tech marketing use cases I've worked on as a tech writer. Docusaurus and ZenDesk get a lot of value from offering integrated i18n systems. Machine translation of technical content is still not great, and all three use cases need tools to manage and track cross-language updates.
> A sync integration with providers like GitHub or GitLab is in the pipeline, but currently you might be able to work something out with Webhooks and Content Transformers, depending on your use-case.
As a tech writer, my use cases today are a hard, management-set docs-as-code requirement for user-facing product docs source that lives as flat files in an open-source repo, and syncing code examples used in tech marketing blog posts to tested examples in the repo to make sure we update posts (or fix regressions) when we break user-facing content. So it sounds like I'd have to wire up two-way change sync and conflict resolution between the repo and Vrite.
As someone who's run docs and support KBs, my broader use case is having a single source of truth for content, and for that single source to be as tool-agnostic as possible.
-
I can see the value for technical marketing writer and blogging, especially in places where devs are also doing tech marketing work. I'm not sure the Vrite-specific features carry enough value to force a switch from something like Ghost or Tina, but I'd give it a spin if I was starting something from scratch.
I'll say that in that context, having an integrated code editor feels like an anti-pattern compared to embedding code from a repo that I can also hook up to tests. I explicitly don't want devs to handwrite code off the tops of their heads into what'll be a blog post or documentation; it'll fall out of date with the product because it's not integrated with it/tested/in CI. It might not even be a correct example to begin with, but as an external tool that tries to feel like an IDE but isn't actually integrated with my codebase, Vrite can't know or figure that out. The Vrite editor just feels like the wrong part of the pipeline for writing code, especially when you're already going headless.
If the content of just the code blocks in a piece of Vrite content could be pulled via API, I could wrap them in enough context to build tests around them, which would make me feel a lot better. The bottom line for me is that any LOC that any dev writes should live in one place; if I have to copy an example from a Vrite content piece to a file in the repo, I've created a maintenance problem.
(Is that already possible? I poked at the Swagger docs but I don't see in the output whether it outputs block content as objects.)
I think I'd still prefer code to be in the repo and not Vrite, but maybe I'd need to see it in use more to better understand the value of having a decent code editor in a CMS.
But for:
> with more customization, something like this could extend to the documentation space and make writing and managing docs a lot easier
I think the scope of that challenge is quite large, and for the most part low-level writing and managing tasks aren't where there's the most pain.
There's lots of opportunity to address challenges in the product docs and support KB spaces, but there are also lots of requirements needed to get a seat at that table: i18n/a11y, versioning, formal review and approval reqs, supporting branched content/staging/feature-flagged content, allowing various non-text content models like config-file examples and JSON schema. Support KBs want to associate content to tickets and measure deflection. LMS users want curriculum design tools or integrations with the ones they already use.
Being an extensible headless CMS where you can code your own integrations is a valuable feature only to companies that prioritiz...
- When integrating with Git, I agree that having a single source of truth is important. In the ideal case I'd like it to work a bit like Git in VS Code. The edited content is still stored in Vrite, though it can be committed and pushed to or pulled from Git to sync. Kanban wouldn't work for that though (unless it's Vrite-only for management purposes) and some other view to represent the structure of the "documentation project" would have to be used. Also, when syncing with files in Git, some kind of format would have to be used to convert the content back and forth. Not everyone might want to use standard Markdown or MarkDoc (especially if they already have some docs in your custom format), so this should likely be customizable as well (with good defaults).
- I won't really be pushing Vrite into docs-as-code and other spaces like this. The primary use-case is dev marketing (right now) and general documentation like usage guides, explainations, etc., where the content is primarly text with addition of code (in the future). Wrote more on this in this comment: https://news.ycombinator.com/item?id=36339020
- Features like versioning, comments and edit requests are planned. Vrite already saves the history of your edits, so it's a matter of implementing a proper UI to view that.
- I agree that companies won't jump on the tool that they'll have to first develop custom extensions for. That said, the idea with extensions (and Vrite being open-source) is that, once an extension system is ready, community will be able to build and publish extensions, hopefully growing the collection as a whole. I know it's rather hard to pull of, but still possible. That's another inspiration from VS Code, btw.
- The features to fetch code snippets or handle contribution licensing make sense, though they are quite specific. In dev marketing (and often times in docs) you'll still need to write small, custom code snippets that don't necessarily exist anywhere else in the first place. On the other hand, licensing sounds like a custom need to me, and it would make most sense if it was available as an extension.
- In general, my approach to adding features is to create something as simple as possible, but highly versitile. I think highly-specific features can quickly bog-down the entire product (and its codebase). It's not always easy, but to give you a few examples for features you've discussed:
> I18N could be handled with "content variants" which would also be useful when you need to slightly adjust the content for different endpoints (though, in some cases maybe conditional inline content blocks would be better for that)
> Code snippet fetching/sync - likely a system of custom content blocks would be best for this and many other use-cases. You'll still be able to create entirely custom block that fetches content and displays it in a read-only editor or just simple view with syntax highlighting). These could be added via extensions. Adding this functionality to built-in code blocks (either directly or through hooks or something) would be too complex for the core, imo.
> Licensing - don't have anything good for this one as of yet, but likely some hooks in the mids of the editing process.
I think that's the way to go. There's a lot of opportunity there for a tool that's better suited to this work than blog-focused CMSs and Google Docs, but with the same sphere of pick-up-and-go accessibility ("so easy, even a product manager could use it!") without sacrificing the technical hooks to integrate that content with disparate things like LMSs, in-app help, or product docs. Runbook docs might even be a good fit depending on how well Vrite can integrate with the tools being deployed, and would be the right audience for the kinds of people who'd likely write and maintain extensions for it.
Product education teams that are allergic to the weight and complexity of LMSs would probably enjoy it too, especially if a mature extension or frontend pops up that can take one pile of content nodes and conditionally present them as blog posts, presentation slides, and paginated workbooks.
But man... the product docs space is like a 12-armed bear. I'd stay far away from even implicitly raising the possibility of Vrite being a fit for "documentation" from a product point of view. Product docs teams often have the most, and most specific, feature needs ("can you conditionalize my content based on non-Boolean feature flags while outputting to both raw and formatted HTML, PDF, and DOCX, and also linting all the content for style, reading level, and sensitivity, oh and also we need to be able to publish shared content across 36 versions of 7 product lines in 12 languages, including British localization. Also it can't fail any accessibility tests. Also can you make the logo on the output 6.5 pixels bigger, use this font I got off dafont, and match these Pantone color values from our branding"), and also the fewest technical resources to write or maintain things like extensions, and smallest budgets to pull the whole thing off — so they're also always looking at any tool that might even tangentially help them do more with less.
Some feedback (based on a quick skim - you've probably thought about all these more than I have but just in case anything is useful)
- Why include project management? It's hard to beat a tool like Linear, Trello, Jira or whatever people are already using.
- I like the idea of a built-in markdown editor, but I think it's also important to allow technical people to bring their own editor or use git directly. Do you support this? If yes, I'd call it out on the landing page. Gitbook used to do this pretty well but they pivoted to a more GUI-focus and now there are weird bugs if you try to use both their editor and git directly
- I agree with other comments that images are something to get right for something like this. Let people paste from clipboard, upload a file from their machine, or link to an already hosted file. Allow the user to the optimization similar to TinyPNG automatically (maybe also CDN, or at least allow integration with CDN). Assuming you're dogfooding this for your own docs, images are loading very slowly so I assume you're not doing this atm.
Good luck!
That said, great, constructive feedback there, so let me address some points:
- I don't like jumping between different tools. I prefer a consistent, great user experience when available. That's why project/content management is a big part of Vrite. That said, I'd like it to be more customizable to different use-cases people might have so, in the future, other "views" aren't out of question, e.g. list view or folder view.
- I see the point. However, building a product around external products (i.e. other code/text editors) doesn't make much sense to me. However, a "raw Markdown mode" with Monaco Editor or a sync extension for editors like VS Code is in consideration for after full GFM support is implemented. Indeed Gitbook has recently been my inspiration as I'm trying to extend Vrite to handle general tech documentation rather than just dev marketing. Git is a big part of that, and I have some ideas on how to integrate it though, given that Vrite is an API-based CMS, this will be a challenging process.
- Various integrations and asset management/optimization are cetainly important. Images are already handled by Cloudflare's R2 so CDN-wise it's already good - they're just too big. That said, I'm currently working on an assets manager and optimizer for Vrite.
is there a pain for managing content for technical writers? yes, probably. not many products target this niche. is the pain big enough to overcome inertia? that seems questionable, but perhaps it is big enough. i doubt large businesses would even look at a fledgling product like this, as it doesn't solve enough pain for them. it seems that there might be a market in small-to-medium-sized technical businesses that have like 1 technical writer and a few guest postings to use a platform like this.
but does it make sense to target developers at all? perhaps for initial marketing, but i'd conjecture that devs mainly just want to get something out on one platform (whether their own blog, or dev.to, or whatever) and perhaps secondarily on twitter (or similar) for more reach and discussion. it seems to be an uphill battle to get them to switch over to a completely different tool that requires integration to get content flowing to all the right places (which is what a headless cms requires).
in any case, the positioning as a headless CMS falls flat to me. that seems to be leading with a technical detail ("headless") rather than the pain and the solution. my off-the-cuff suggestion is something more like "Content Automation" as the descriptor. similar to "Marketing Automation" (e.g., buffer, hubspot) yours is a CMS plus and an automation platform (in the making). it helps people crank out technical content and put it in all the right places to be seen by the people you want to target.
Marketers, on the other hand, love headless CMS tools. They're the ones who forced me to use one, since our main website and blog were also built on Contentful at the time. I think headless CMS tools offer the perfect level of configuration and modular authoring for them without the daunting hurdle of having to learn to code(ish).
I imagine a tool(chain) that can take Swagger generated from annotations in code, and combine it with a folder containing Markdown files for "free form" documentation, and generate a Hugo/Jekyll static site that can be deployed in Cloudflare Pages in docs.mycompany.com
Considering how few other companies are willing to toss more than a few bucks at technical writers and tools, the difference is pretty stark.
When we redid the Mux docs (https://docs.mux.com/api-reference) we actually just decided to build our own renderer. It really wasn't as bad as you might think, at build time we pull in the JSON version of our OAS spec and render it as a static build in our Nextjs app. Don't get me wrong, it wasn't trivial, but the benefit of having complete control over the output has been well worth it.
They open-sourced parts of it here: https://markdoc.dev/
HN discussion here: https://news.ycombinator.com/item?id=32835751
I was looking into implementing custom and conditional content blocks in Vrite editor but wasn't sure about the output format. MarkDoc seems like a great, standardized extension of Markdown that would be perfect for this use-case.
Will try to work on that.
It's early, but worth checking out.
[0]: https://doctave.com/
* Your website looks slick and kinda well designed (though there seems to be too much information moving around).
* The documentation starts with getting the user to sign up for the hosted version (SaaS).
* There is no pricing information or FAQ about pricing and business model.
* Though the code seems to be on GitHub and the license there is stated as AGPL, there are no prominent links to anything about self-hosting either on GitHub or on your main site. So I’m not sure why this is AGPL licensed but also talks the user into signing up to the hosted version in the docs.
I think the self-hosting documentation will help bring more people to try it within their own environment without worrying as much about privacy and security.
The intention isn't to "talk users into" the hosted version, but just build interest, for which the hosted version serves best at the moment.
Other points r.e. landing page are valid and I'm generally aware that I should focus more on content than design. Easier said than done though :)
While the "Big XML Specs" (aka DITA, S1000D, DocBook) allow you to re-use content, you can get the same functionality from Asciidoc or ReStructuredText. You can ALSO get the same functionality from Markdown, but it requires extensions, and the problem with THAT is that the functionality will change from instance to instance. Adoc and RST have transclusion and conditionals in core. I think Asciidoc is the right way to go here, but my reasoning might not be applicable for someone outside of the hard industries (manufacturing, aerospace, defense).
But just because you have transclusion and conditionals, that doesn't mean you're ready to start re-using content. Content re-use, the concept often called Component Content Systems, introduces a level of complexity that's almost always underestimated, and it's inherently dependent on information architecture in a way that a unified or natural document isn't.
Information architecture is going to be driven by product architecture, and if the product architecture is missing or wrong, then you probably shouldn't try to architect the documentation. Re-use only works when the product makes sense.
Here's an example.
Let's say my org makes planes. We make a product called SuperPlane. It has three variants, A, B, and C. Each of them is composed of modules: Wing, Fuel, Cockpit, Propulsion, Empennage. The product, in this case, is architected. SuperPlane modules share enough commonality so that the documentation for each module can be shared across all variants. So I have a "book" for A, for B, for C, and a single document module for Wing. Inside of the document module there are blocks of conditional content, for each of the variants. So when I run a book for A, it pulls in the Wing section, the it's customized for A as the conditionals are processed. Same for B and C: multiple deliverables, re-using the same modules.
My information architecture - filenaming, chunking, conditions - rides from the product architecture. The product architecture is solid, and so am I.
Now let's say our Maximum Leader has decided to acquire a car company, and has decided to make the flying car the D variant of SuperPlane. It's got an integrated wing and fuel module, so now, we lose content history with our A-B-C Wing and Fuel modules, in spite of the fact it's supposed to be equivalent. Its cockpit module shares no interfaces or commonality with the other cockpuit modules - so the module for Cockpit has a gigantic conditional section that largely parallels the others, in the same module, which makes assessing change impact really difficult. With the introduction of Variant D Superplane, the Superplane product is no longer architected, and our information architecture got blown up as well.
This is the core reason why component content systems (CCSs) are so hard. The end product depends on lots of stuff outside of the tech writers' wheelhouse, and unlike a document - which you can look at any old time you like - when the information architecture is busted in a CCS you might not even be able to get your content out of it. CCSs replace the natural language of document structure with the constructed language of information architecture, which is a bigger leap than I think many people realize; it fundamentally changes what your documents actually are. The original concept of CCSs did not come from a linguistic or information background, they were largely psychology academics and/or dealing with an EXTREMELY limited corpus, and you can see the trace of this in the awesome pattern of failure for most CCS systems to the present day. This is markup-agnostic; it doesn't matter if you're doing it in S1000D, DITA, DocBook, ReStructuredText, or Asciidoc.
So how do you check product architecture?
That is complicated, and it's going to depend o...