suitenumerique
Publish a doc to the Web
Is your feature request related to a problem or unsupported use case? Please describe.
Teams need a simple, compliant, and collaborative way to publish documentation or content on the web while complying with accessibility and security standards.
Many teams are using Docs as a content repository and use public link to publish their content to the web. This is far from ideal as the admins of a Docs intance might not have planned for their to domain to be used to host user generated content. Currently doesn't propose any of the following features:
-
search engine indexation
-
custom domains or custom slugs
This creates a gap for use cases such involving public-facing content (e.g., help centers, project documentation) that must comply with government standards.
@sylvinus even made this [PR](https://github.com/suitenumerique/docs/pull/1213) to add an API so that Docs can be used as a Headless CMS, where content stored in Docs is exposed via API for custom front-end rendering.
Describe the solution you'd like
❓I'm hesistant should we have 2 features : publish to the web and public links ? The difference I see with a document that is published to the web is that it is index by search engines, has a custom slug, can be served as a static document. I've chosen to explore the "Publish to the web" as different feature scenario in this issue.
We propose a "Publish Docs to Web" feature that allows users to publish Docs content to the public web. It should be a available as an extra link sharing parameter.
The solution should:
Core Features
-
Owner and admins only: only members with these role can publish a document to the web.
-
Members edit only: A document published to the web can only be edited by it's members.
-
One-click publishing: Publish Docs content to the web should be as easy as setting a document to public
-
URL slug customization: Let users define clean, readable URLs for published content.
-
**Specific Domain and TOS for public content, similar as github.io ( check this article ), for security and compliance reasons. When a user will "publish to the web" his content will be served under a different domain, that's the url he should use to share it publicly
-
SEO and accessibility: Ensure published sites are SEO-friendly and meet accessibility standards.
Feature that we won't be tackling :
- Custom domains and SSL: Allow users to map their own domains, with SSL support (compliant with SIG policies).
- Multilingual support: Publish content in multiple languages.
Describe alternatives you've considered
Use the public link parameter.
Discovery, Documentation, Adoption, Migration Strategy
Discovery
-
User interviews: Engage with lead users (e.g., Sites Faciles teams) to validate needs and gather feedback.
-
Technical investigation: Understand why some users (e.g., Sylvain) built custom CMS solutions on Docs, and identify common pain points.
Documentation
- Design proposal for how a doc published as website looks like : FIGMA
-
User guide: Step-by-step instructions for publishing a doc to the web
-
Compliance checklist: ensure users understand legal implication of publishing a doc to the web.
Adoption
- Pilot phase: Roll out the feature to a small group of lead users for testing and feedback.
Migration Strategy
- Identify users using the public sharing link to publish docs to the web (docs that have a lot of views) to offer them to the "Publish to the web" feature.
Do you want to work on it through a Pull Request?
Yes with the Docs maintainers team.
Next Steps:
- Validate this feature request with internal stakeholders (legal and information department of DINUM.
LGTM.
Specific Domain and TOS: for public content, similar as github.io ( check this article ), for security and compliance reasons. When a user will "publish to the web" his content will be served under a different domain, that's the url he should use to share it publicly
Regarding the specific public domain, I see that the screenshot uses docs.io and I should mention that first, this domain is already registered by Microsoft and points to the MS 365 website and second, per the Aita rules, the IO country code will disappear after the retrocession of the Chagos Islands to Mauritius and, per ICANN rules, so should the .io top-level domain. This probably won't happen and I'm pretty sure the rule will be changed or an exception be made, but creating new .io domains should not be encouraged at the moment (check this article for a longer explanation.)
Custom domains and SSL: Allow users to map their own domains, with SSL support (compliant with SIG policies).
Would this work at the root of the domain (ie a full website with the doc shared directly at https://myfancydomain.fr/), or inside a path (e.g. https://myfancydomain.fr/mydoc/) or both?
Hey @Ash-Crow I corrected a few mistakes in the original issue text, we won't go for a docs.io for sure and won't implement custom domain and multi-lingual support for now.
@rl-83 @arnaud-robin looking forward for your inputs on this. Thanks
Investigating how github.io works I realized they are serving all their content statically. Which is interesting for optimization reasons. There might be no need to display modification in real-time for a user that is just visiting a document published to the web. (To be checked though).
Though this approach requires a publication workflow. Meaning there is a working document on which members make edits and they decide when to publish (they'll publish a version of the content). If they make further modification they'll have to publish the changes (and a banner should let them know when there were edit posterior to publication and suggest to republish).
The published version could be exported in its static version (html css) and be exposed on the specific domain mentionned above.
This approach might not work if we consider that a user might want to publish a doc with sud-docs and offer a search bar for navigation.
Considering this it's also interesting to check how Notion works.
- Like GitHub they have a dedicated domain (notion.site).
- There's no publication workflow
- The modifications are not displayed in real-time on published page, you have to refresh to get the latest version
- They do not offer a sidebar for subpages but there is a search feature displaying the subpages as results
I like this approach way better personnaly. Except I'd display the sidebar with the document tree.
To let you know, Next.js has a SSR mode, in SSR it is "easy" to do that, even more, it would need a server though.
