Eine neue Website für Gladys 4?

pierre-gilles · 26. Mai 2020 um 15:49

Hallo zusammen!

Während die v4 bereits über 1.200 Mal seit dem Start der Alpha-Version installiert wurde, ist die aktuelle Gladys-Website (gladysassistant.com) immer noch die für die v3 erstellte Website. Ich habe die Informationen zur v3 schrittweise ausgeblendet, aber das ist nicht einfach, denn diese Website wurde nicht für die v4 konzipiert ^^ Das Design der Website ist immer noch ein altes Bootstrap-3-Theme, das schwer zu aktualisieren ist.

Ich möchte die Website neu überdenken, um neuen Nutzern zu helfen, Gladys 4 zu verstehen und Lust zu machen, sich auf das Abenteuer einzulassen!

Das Ziel dieses Themas ist es, darüber zu sprechen, was wir auf der Website wollen und wie wir es umsetzen.

Funktionale Spezifikationen

Für mich muss die Website eines Open-Source-Produkts folgende Fragen beantworten:

Was macht die Software? Kann ich XXX damit machen?
Mit was ist Gladys kompatibel? Welche genauen Geräte? Habe ich ein Gerät « fibaro XX », wird es von Gladys unterstützt?
Wie installiere ich Gladys? Auf einem Raspberry Pi? Auf einem Synology? Auf einer Freebox Delta?
Ich habe eine Frage, wo stelle ich sie?

Aus diesem Grund habe ich mit dem Design einer Website für Gladys 4 begonnen:

Es ist ein funktionales Design, das eigentliche Design (Schriftarten usw.) ist hier noch nicht gemacht.

Ihr werdet mehrere Dinge bemerken:

Die Dokumentation ist zurück auf der Hauptwebsite. Ich denke, die Dokumentation ist das Herzstück eines Open-Source-Projekts, und ich finde es schade, sie auf einer separaten Domain zu haben, als ob sie nicht wichtig wäre: sie ist das Wichtigste!
Wir haben oft über einen « Integrationen »-Tab gesprochen, der alle von Gladys unterstützten Geräte auflistet. Ich habe viel darüber nachgedacht, und ich beginne zu verstehen, wie wir es integrieren werden. Genauso hat es seinen Platz auf der Hauptwebsite von Gladys. @AlexTrovato, das wird dich interessieren
Jedes unterstützte Gerät hat seine eigene Seite, und es ist möglich, auf der Seite des « Geräts » Kommentare zu hinterlassen, um Fragen zu stellen. Mal sehen, ob wir Discourse auf dieser Seite integrieren können, damit die Nachrichten im Forum sind

Technische Spezifikationen

Wir sind ein Open-Source-Projekt, die Website muss Open-Source sein, wie sie es jetzt ist. Jeder kann die Website bearbeiten
Die Website ist mehrsprachig (EN/FR)
Blog-Artikel werden in Markdown in Dateien gespeichert
Die Integrationen werden in Markdown in Dateien gespeichert (eine Datei pro Integration & pro Sprache)
Die Website ist generiert und statisch

Was den statischen Website-Generator betrifft, verwenden wir derzeit Jekyll, einen in Ruby geschriebenen statischen Website-Generator. Er funktioniert gut, ist aber relativ langsam beim Generieren + die Tatsache, dass er in Ruby geschrieben ist, ist unpraktisch: Ich kenne mich nicht mit Ruby aus und man ist schnell blockiert, wenn man etwas Custom machen will

Ich möchte zu einem Generator in JavaScript wechseln, wie Gastby oder NextJS. Mir scheint, dass NextJS einfacher ist als Gastby, aber ich habe noch nicht ganz zwischen den beiden entschieden

Was denkt ihr?

VonOx · 26. Mai 2020 um 17:21

Dass du JS-Dev bist, steht außer Frage ^^

Witz beiseite, ich stimme dir bei der Dokumentation und den Integrationen zu. Ansonsten habe ich keine große Meinung.

Normalerweise, wenn ich auf eine Website mit dieser Art von Begrüßung (Slider / Features usw.) komme, ist das Erste, wonach ich suche, die Dokumentation, und oft, um diese Frage zu beantworten
Und wenn die Dokumentation keine Suchleiste hat, gehe ich weiter (ja, ich bin faul )

Ich weiß nicht, ob du es gesehen hast, aber nextjs hat einen Leitfaden für den Benutzer erstellt, ich finde das Ding ganz nett

pierre-gilles · 26. Mai 2020 um 17:52

Ich auch! Aktuell gefällt mir das, was wir haben, nicht wirklich, ich denke, es wird einfacher zu verstehen sein für Neueinsteiger.

Das erinnert mich daran, dass ich die Suchleiste in der Dokumentation vergessen habe, das sollte die Basis sein.

VonOx · 26. Mai 2020 um 22:57

pierre-gilles · 27. Mai 2020 um 19:38

Ich nutze es schon seit mehreren Jahren Auf der Website und im Forum. Eigentlich gibt es schon eine Kompatibilitätsseite, die ich für Gladys v3 erstellt hatte (https://gladysassistant.com/fr/compatibilities/), aber ich habe sie vorerst ausgeblendet, da sie nicht aktuell ist.

Das Amazon-Partnerprogramm bringt wirklich nicht viel ein, ich setze eher auf Gladys Plus, um für meine Arbeit unterstützt zu werden

pierre-gilles · 27. Mai 2020 um 20:59

Das ist im Moment nicht geplant, es ist schon eine zusätzliche Komplexität, mehrere Abonnementspläne zu verwalten. Ein Plan ist für den Moment schon gut

pierre-gilles · 10. Juni 2020 um 19:13

@lidian das ist nett! Im Moment sind wir eher in der Konzeptionsphase als in der Implementierung, ich werde eine Nachricht posten, wenn ich mich auf der Website anmelde

In der Zwischenzeit zögere nicht, uns bei Gladys selbst zu helfen, es ist Preact (leichteres React) + Node.js, und wir haben viele offene Aufgaben! (Issues · GladysAssistant/Gladys · GitHub), jede Hilfe ist willkommen

pierre-gilles · 16. Juni 2020 um 10:02

Ansonsten mag ich Docusaurus sehr:

Damit kann man Websites mit einer super sauberen Dokumentation, Suchfunktion, Dark Mode erstellen, alles basierend auf Markdown-Dateien und benutzerdefinierte Seiten sind in React.

Aber ihre Version 2 ist noch nicht mit der Internationalisierung kompatibel…

Ich zögere sehr, ob ich eine neue Website mit Next.js starten soll, aber ich riskiere, vieles neu zu erfinden, was Docusaurus nativ bietet, oder ob ich warten soll, bis Docusaurus seine Version 2 veröffentlicht, um unsere Website migrieren zu können.

VonOx · 16. Juni 2020 um 10:25

Ich habe es gerade schnell getestet, es ist nicht schlecht und allein für das dunkle Thema sage ich ja ^^.

Ich denke, es lohnt sich zu warten, und nichts hindert uns daran, mit der Arbeit zu beginnen.

pierre-gilles · 16. Juni 2020 um 13:20

Man kann tatsächlich gut mit einer rein französischen Website beginnen, sie auf eine andere Domain stellen (z. B. ein Subdomain von gladysassistant.com), bis sie die Internationalisierung veröffentlichen. Aber was mir Sorgen macht, ist, dass sie langsam sind und das erst in einem Jahr rausbringen… Ich glaube, sie arbeiten seit 2018 an der Version 2.

pierre-gilles · 16. Juni 2020 um 13:52

Ich habe erste Tests mit Docusaurus v2 gemacht, das ist echt stark!

Sie nutzen Infima für das Styling, das ist wirklich nicht schlecht

VonOx · 16. Juni 2020 um 13:55

Kopierer

pierre-gilles · 16. Juni 2020 um 13:58

Aha Bis die Internationalisierung in Docusaurus verfügbar ist, frage ich mich, was uns daran hindert, zwei Ordner (einen « fr » und einen « en ») zu erstellen und zwei verschiedene Docusaurus-Projekte zu haben. Wir können versuchen, so viele Dateien wie möglich zu teilen (z. B. React-Komponenten für die Startseite), aber ansonsten werden alle .md-Dateien unterschiedlich sein.

VonOx · 16. Juni 2020 um 14:01

github.com/facebook/docusaurus

Docusaurus 2

ouvert 05:17AM - 20 Jun 18 UTC

fermé 09:16AM - 10 Jun 21 UTC

yangshun

# Update 03/19/19 We have started a Roadmap/Feature requests page thanks to t…he awesome folks at Canny.io. Have a go at it on our WIP v2: https://v2.docusaurus.io/feedback/ --- These are some of the problems I'm seeing in Docusaurus now and also how we can address them in v2. A number of the ideas here were inspired by VuePress and other static site generators. In the current JavaScript-based static site generators ecosystem, there are the following libraries: - https://vuepress.vuejs.org/ - https://www.gatsbyjs.org - https://github.com/nozzle/react-static - https://github.com/phenomic/phenomic - https://docsify.js.org/ - https://github.com/lord/slate - https://middlemanapp.com - https://github.com/jnordberg/wintersmith - https://github.com/jaredpalmer/razzle - https://github.com/pedronauck/docz Useful libraries - https://github.com/c8r/x0 - https://github.com/mdx-js/mdx - https://github.com/jonschlinkert/gray-matter My proposal for D2 is that Docusaurus be responsible for documentation content, routing, translation and versioning, leaving layout and styling to the end user. Docusaurus would provide a default theme and a few common layouts that the user can use, or ignore if they want to build their layout from scratch. It's not a good idea for Docusaurus to maintain the entire layout and styling as these stuff are hard to make improvements without breaking existing users' code. A Google Doc where we go into more details can be found [here](https://docs.google.com/document/d/1N_dA9W0CgMpNg9jl2kfWRKoB6yE5Up9isgTK9Ol1dLk/edit#heading=h.nueldtp4gi18) ## D2 Design Principles - Easy to learn but most things are still achievable by users, even if it takes them more code and more time to write. No abstractions beat bad abstractions, and we don't want users to have to hack around the wrong abstractions. Mandatory talk: [Minimal API Surface Area](https://www.youtube.com/watch?v=4anAwXYqLG8) - Users won't feel overwhelmed when looking at the directory of a D2 project. It should look familiar to users familiar building web apps and websites and is easy to build on top of. - We should not lock-in our users to use our plugins or our CSS. Certain lower-level infra level stuff like React Loadable, React Router are fine, but not higher level ones, such as choice of Markdown engines, CSS frameworks, CSS methodology. - The separations of concerns between each layer of our stack should be clear - well-abstracted and modular. ## D1 Problems and Proposed Solutions ### Infra **Current Problems** - Routing logic is separated and resides within both server and generation code, leading to duplicated logic and harder to ensure that code working in server mode also work in generation mode. - Routing is not declarative. Hard to understand what possible routes there are in Docusaurus. - Build pipeline is imperative and quite tangled. - Does not allow adding local vendor CSS and JS (https://github.com/facebook/Docusaurus/issues/534) - New features are mostly enabled via siteConfig - siteConfig will bloat over time and become unmaintainble. - Current architecture is a bit tangled and makes it hard to introduce plugins. - Many components relies on `process.cwd()` too much (mostly for siteConfig), making it very hard to test. - LiveReload does a full-page reload, and page reloads for changes of all files. **Suggested improvements** - Use a module bundler like webpack (or Metro if possible, since it's also by Facebook). - Static pages can be generated using (https://github.com/markdalgleish/static-site-generator-webpack-plugin) - Assets should be fingerprinted (should be trivial with webpack) - Use webpack-dev-server during development which enables hot reloading - only reload the modules which changed. - Rearchitect architecture to introduce hooks into the development and build phase so that a plugin system is possible. - Keys casing are not consistent - camelCase in siteConfig and blog front matter but snake_case in docs front matter. ### HTML/CSS **Current Problems** - Raw CSS without any preprocessor. Hacky variable substitution approach using regexp. - Docusaurus controls much of the styles and layout, which makes it prone to breaking end users code who customize. - All CSS is compiled into one file. - HTML/CSS is self-written and doesn't follow CSS framework best practices. Typography is not great (margins and paddings are not consistent)/. Partially fixed in https://github.com/facebook/Docusaurus/pull/757. - Hard to do theming on top of current CSS structure. Limited to changing of colors and fonts. - Site layout is not customizable - EDIT: Just found out it is (https://github.com/facebook/Docusaurus/pull/128). - Docs/blog layout is not customizable. - No 404 page. **Suggested improvements** - Layout and styling should be controlled by theme and user. Docusaurus should just provide the data (content, translation, versioning), props and a default theme. This is the approach taken by many static site generators as well, such as Jekyll, Gatsby and VuePress. VuePress allows ejecting of the default theme for further layout customization. - Follow CSS frameworks best practices - Use rem for units, allow specifying margin width, etc. - Allow user to select their own CSS preprocesser. - Allow setting styles and scripts for specific pages only. Use case - some sites like Babel, Prettier and Reason have playgrounds where they only want to load specific scripts and styles. - Make Docusaurus pages/components more customizable (https://github.com/facebook/Docusaurus/issues/249) - Add a 404 page. ### JavaScript **Current Problems** - JS code in pages is currently not being transpiled by Babel. We have to write ES5 in code that will be sent to browsers. - React is used as a templating engine for static content; we're not using any of its view library features. Interactivity has to be added through script tags and `dangerouslySetInnerHTML`. **Possible improvements** - If the user adds interactivity to their React component/page, we should include React library on the page and hydrate the component after the page has been rendered. ### API **Current Problems** - CLI commands should be using `docusaurus <command>` (instead of `docusaurus-command`) which is more conventional (see Yarn and Git). - Docusaurus-provided components are required using a relative path which looks a bit odd and may break if we change the library's internal directory structure. **Possible improvements** - Rework the CLI commands. Should be just a matter of renaming and shifting them into `docusaurus` core. This also solves the problem of having to publish `docusaurus-init` as a separate package. - Export docusaurus components on the main npm file itself. Add even more common components (we can consider creating pages as components as well). ### Blog **Current Problems** - NA **Possible improvements** - Allow for commenting support (via a plugin and not siteConfig as how it is currently done) - Allow customizing of date. - Draft mode for posts - Tags, Categories ### Markdown **Current Problems** - Only reads YAML, does not support different kinds of front matter. - Unable to embed content from other Markdown files. **Possible improvements** - Add reference style linking. - Add page tabbing (https://github.com/facebook/Docusaurus/issues/45), probably via a Remarkable plugin. - Allow importing markdowns in other markdowns. - Line highlighting within code blocks. - Support embedding React components in markdown. - Emoji support. - Check that internal page links and anchors work fine. - Support [special block tags](https://vuepress.vuejs.org/guide/markdown.html#custom-containers) like in VuePress for tip/warning/danger markup. ### Search **Current Problems** - We're using Algolia as the only form of search now. Algolia search is a third-party service that requires internet and doesn't work behind VPN/offline. **Possible improvements** - I really like Algolia search as it's useful and so simple to use. But we could also come up with alternative offline search mechanisms to get around the limitations mentioned above. At my previous company, I added [offline search for a static site](https://engineering.grab.com/) via Lunr.js. It works by looking through the markdown files and generated a static index of the content during build time. The searching and rendering of search results is purely done on the client side. It roughly works - https://engineering.grab.com/search.html?q=react These are my two cents. Feel free to chime in (:

pierre-gilles · 16. Juni 2020 um 14:15

Ich habe es gesehen, aber « hoffentlich irgendwann in den nächsten paar Monaten » ist nicht unbedingt beruhigend

Naja, mit dem, was wir schon haben, bin ich sicher, dass wir bereits eine Website auf en/fr erstellen können, indem wir einfach die beiden Websites trennen und eine doppelte Generierung durchführen.

VonOx · 16. Juni 2020 um 14:17

Wie die rc1 von Gladys #Witz

pierre-gilles · 16. Juni 2020 um 14:43

In 20 Minuten erledigt:

Hyper cool dieses Tool!

pierre-gilles · 16. Juni 2020 um 15:05

Ich habe diesen ersten Proof of Concept in einem Git-Repository hinterlegt:

Jetzt müssen wir es schaffen, die doppelte Website „fr/de“ für die Internationalisierung zu erstellen

pierre-gilles · 22. Juni 2020 um 08:47

Ich habe gerade die Migration der englischen Dokumentation abgeschlossen:

Jetzt mache ich mich an die französische Dokumentation.

Danach bleibt noch:

Der französische Blog
Der englische Blog
Die Startseite (EN+FR)

Ich werde wahrscheinlich versuchen, eine erste Bereitstellung auf einem Subdomain vorzunehmen, bevor ich das Ganze pushe

pierre-gilles · 22. Juni 2020 um 13:24

Booon

FR-Dokumentation fertig
EN-Dokumentation fertig

Ich bin jetzt auf der Integrationsseite!

Thema		Antworten	Aufrufe
Nouveau site & nouvelle documentation pour Gladys 4 🚀 Actualités	7	1123	27. Juli 2020
Lancement de Gladys Assistant 4 ! 🚀 Actualités	59	4820	25. Januar 2021
[Site Docusaurus Gladys] Build en erreur depuis les derniers ajouts côté Airtable Développement	26	1120	20. März 2021
✨ La documentation Gladys évolue : découvrez les nouveautés! Actualités	17	574	9. Juni 2025
Gladys Plus évolue : nouvelle page, essai gratuit simplifié et accompagnement Actualités	18	364	26. Mai 2026

Eine neue Website für Gladys 4?

Verwandte Themen