Open
Description
This request came out of my work on #1815 where I added some single-sourced content and cloud icons anyone can use. Things generally work, but require you to include files from the shared/ path manually or to add the elastic/docs repo as a resource. The "anyone can use" part could be improved if every book simply got the elastic/docs repo by default, specifically the shared/ folder.
Some additional discussion and planning would be required, so this might not be a simple switch.
Benefits
- You could use the standard attributes, the shared versions files, and single-sourced tasks we define without having to think about where they live and manually embed them in your book. They'd just work. Today, books manually embed these files.
- We'd encourage people to use these standard files, because they're always available. Honing in on common usage for product name attributes can only help improve our coming reuse of docs source from multiple repos into books that aren't as product centric as they are today. Compare that with using your own homegrown stuff that just won't build if you try to embed it in another book.
- Shared images like the cloud icons would no longer require workarounds to be usable. I had to put our cloud icons on S3 and reference them by URLs, because of how the default
{imagesdir}works. As is, to make the copies in shared/images work, you have to add--resource=$GIT_HOME/docs/for every book build alias or update conf.yaml for each book to enable shared images (shoutout to @lcawl for the tip on how to make this work!).
Potential pitfalls
- Books that define their own product name attributes that conflict with the shared files will throw build errors until they get updated.
- Lisa discovered #1834 Previews do not recognize which books are affected by image updates.
- I want to say that if you have multiple repos containing the same filename, say ess-getting-started.asciidoc, you might run into an evil twin issue where you expect one file to get used only for the other one to actually get pulled in. (Lisa might have pointed this out as well, but I have run into an evil twin problem at a previous job where much troubleshooting and hilarity ensued.)