Docs: Custom CSS. Request to re-prioritize.

[rsweetland]

Postman for Mac
Version 5.3.2
OS X 15.6.0 / x64

I know custom CSS is already on the roadmap. This ticket is my attempt to convince you to release a simple implementation sooner rather than later : )

I would be more than happy with something as simple as this...

• Restrict to paid accounts.
• If a global environment variable exists called {{styleshet_url}}...
• Render the stylesheet link in the header.

Alternatively, a text input could be placed in the Edit Collection dialog. Or even a text input box whose contents are rendered in a <style> tag; but the above seems the simplest.

Because each docs site is on a subdomain (or custom domain), security issues seem like they would be negligible.

This addition of custom CSS, even via the simplest methods, would take Postman Docs to new heights. And the effort / impact seems to be very worthwhile. Please consider moving it up? 🙏

[hongaar]

I'd be very, very happy if this card was moved up on the list. I'm almost daily looking at the Trello board for any progress 👀.

Could the Markdown parser be modified to let through <style>...</style> blocks in the collection description?

That would be a very nice quick fix so we can finally fully customise the documentation page!

[rsweetland]

Update (4 months later):

I tried my best to make the Postman docs work without custom css / JS but ended up going elsewhere. The last straw was a lack of named anchors on headings. (All of which is remediable by custom JS / CSS).

After trying various options I just decided to pay $50/mo for readme.io. Postman still serves as the documentation for only REST API endpoints. I would have rather paid Postman.

From a product perspective, docs may be one of your most powerful, untapped marketing resources: Developers would happily share a branded version of their docs site with other developers, as long as it has a nice UX. The organic marketing potential is huge. As of now, Postman is relegated to our internal team and a button on our docs site. It could be so much more!

[scottydocs]

Any news on this? This could be real deal breaker as to whether we use Postman or another tool.

[hongaar]

Too bad. I really don't want to setup another documentation project somewhere else and coordinate/automate changes to both of them, and I hate to admit we are considering a similar setup as well - we start to miss this feature too much.

/ping @SamvelRaja @godfrzero

[sankalp0o]

@rsweetland @Jwscott22 @hongaar just curious, what kind of customisations are you most looking forward for?

[scottydocs]

@sankalp0o just the ability to add a custom logo to replace the Postman one, import and use our own fonts, edit the header and background colours. All the standard options offered by CSS essentially.

We couldn't use Postman docs in their current state because we need the ability to style the page so it fits our branding/ looks like the rest of our documentation.

[hongaar]

@sankalp0o agree with @Jwscott22. We'd like to have the ability to fine-tune the general look & feel of the entire page (header, sidebar). The most important one for us is the ability to modify the styling of the main content (fonts, spacing, colours, etc. etc.) as currently its layout is not ideal, e.g. we'd like to turn: .

this


into this


.
Basically a simple text editor allowing us to inject arbitrary CSS (with the obvious exception of loading external resources / sensible CSP) would be enough.

Oh, and a customizable favicon would be great! 😉

[hongaar]

Postman documentation is starting to look a bit outdated and the lack of custom CSS is making us look at other solutions now. The feature is on the Trello board since the beginning of 2017, but still in the planning phase (least priority).

@godfrzero @sankalp0o any update on this would be appreciated.

[XaWin]

Fully agree with all the above, customization is really limited presently.

[brendanknowles]

+1. Unsure why this is such a challenge to provide but it would really help us out too.

[rsweetland]

@sankalp0o Is security the main concern?

I'm going out on a limb and assume this is the case. If so, maybe the Postman community can lend a hand in confirming / talking through a secure implementation.

Here are some questions / ideas (again, assuming security is the issue..ignore this comment if that's not the case):

• Do the Postman-generated docs store / ask for any sensitive information from users? I don't think so but I am not certain – the Postman app seems to take care of the actual API interaction. If the API docs do collect sensitive information, I understand locking this down.

• If there is, in fact, no sensitive data in the docs, the next question is about subdomains. Are all docs sites on their own subdomains? If so, CORS is here to help. Many big companies Squarespace, Weebly, Shopify, etc rely on this to sandbox different subdomains.

Speaking for myself, I would be very willing to sacrifice interactivity for aesthetics. If you just provided a locked down, static, generated docs site on a subdomain with the means to inject custom CSS / JS it would be awesome.

The Postman ecosystem is very robust and I don't have the full picture. But if security is of concern, maybe we can help discuss implementations, possible attack vectors and tradeoffs to shipping a locked down, yet visually customizable system.

[godfrzero]

Security is one concern, but the one that bothers me more than that is maintainability. Allowing the injection of custom CSS is not a challenge at all, when looked at in isolation. While the documentation hasn't changed visually (at least, to a degree worth noting) in years, the underlying HTML has been rewritten multiple times for performance improvements and whatnot.

Any custom CSS which is written at any point in time will be bound to the HTML structure at that time (the degree of binding depends on how specific the CSS rules themselves are). Now the custom CSS problem becomes slightly more complex, because I can no longer push out security or performances fixes which impact the underlying HTML without the risk of breaking someone's custom styling. And I'd like to avoid non-deterministically breaking public docs at any point. So, allowing just custom CSS would lead to a situation where we'd eventually be locked into the current HTML structure (depending on custom CSS adoption, the amount of customization, etc.).

Now, of course, we do want to allow users to customize their public docs, so it's really a question of "how" and not "if". In order to work around this coupling between CSS and HTML, we'll have to allow customization of both. This is what we have in mind right now, and the end result will be a system which allowing the selection of a theme while publishing. Themes can be customized into a copy of the theme specific to a user, so the risk of an update breaking a public doc is completely gone.

Though now it does come with other (possibly minor?) risks: Performance and security fixes now fall upon the theme maintainer. The default themes can be patched by us, the custom themes cannot. As the platform providers, I feel we have a duty to design the system in a way which makes it difficult for any user to shoot themselves in the foot, so there will be some safeguards in place to mitigate certain classes of XSS. However, since user code has to execute with almost full privileges in order to render the theme (since the theme will be custom HTML + CSS anyway), the protection we can put in place via CSP is limited. The security aspect of allowing custom HTML + CSS is something I'm still thinking about, but I don't see it as a blocker. So, for the status update: We're working on the implementation, design, and security details relating to themes. Once these things have been figured out with popular edge cases in mind, we can come up with a timeline and actually have an ETA for this.

[rsweetland]

@godfrzero Thank you for giving us so much context and sharing your thoughts with the community. I get it!

The template idea is awesome. Appreciate you not deterministically breaking people's themes with updates : )

Regarding security, what if you allow for customizations only on "verified domains" (ie, custom domains the user points to their docs)? This would isolate static docs from the other functional pages for teams, etc. Just a thought that could mitigate some foot-shooting.

Thanks again for the update. Long live postman. 🖖

[godfrzero]

It's highly likely that advanced customization (like themes) will be available only on custom domains. We can't allow arbitrary code execution on our domain, for obvious reasons. Limited customization (brand colors, custom logo, some layout controls) will be available to everyone regardless of domain.

[hongaar]

Appreciate the update.

Unfortunately it doesn't give me a very comfortable feeling, as it feels customisation options are even farther out then they might have been if CSS customization was still on the table (creating a theming system definitely sounds more involved to implement).

Personally, I'd be absolutely fine with breaking changes to the DOM structure as it will be unlikely to result in an unusable site (unless you've really got out of your way to customize the layout). It'd be okay risking those one or two days the site would look a bit off, compared to the current situation, where it's looking a bit off all the time..

[mhowes82]

Please add support for Custom CSS! We would love for our Postman docs to match our company branding/style guide.

[rsmck]

I've been directed to this by Support when pointing out the the WYSIWYG Preview in the app and what actually ends up on the published documentation is completely different with respect to font, spacing etc. The app preview is much cleaner looking than the end result.

Ultimately, custom CSS would fix this problem too, although it would be nice if the default actually matched the Preview.

[Boorda]

Also highly interested in this feature. It is a bit concerning though that this ask has been sitting here for over four years now.

[hongaar]

This seems to be missing from the new public roadmap now. Is this still on the radar @Raja-Simha or should we start considering alternatives? Would be good to get an update on this so we can plan for the future.

[viveksoundrapandy]

@postman team, your support team advises to follow this thread but we don't see this in the roadmap. Kindly advise

[kleblanc-igloo]

Also struggling to implement Postman as a corporate documentation source without the ability to adjust it to match our corporate branding. Would love to see more fine-tuned customization available.

[VladislavLazarov]

Dear @postman-support team,

Is there a way to issue a custom CSS request to update custom logo visualization on postman documenter page? The logo we need to upload is rectangle but the solution resize to square which is not ok.

Thanks