The docs-development process may not support adding image and other files (WM)

[smurthys]

PS: I am creating this issue so we can collectively discuss and receive notifications as new comments are added.

Context: We have add at least two instances where non-markdown files are to be included in the docs folder. See #136 and #139.

In general, we have the need to add HTML/Visio/image files to the docs folder with design notes and these files will have to be linked to from docs pages which are markdown (MD) files.

On the surface, this does not sound like much of an issue, but I worry our development process for docs may not support this ability: at least not very easily. Our docs-development process uses the Wiki as the "development environment" to write the docs and it worked very well in M1: We need to use the Wiki so anyone can easily update any page directly online and also avoid the approval process which can be both labor and time intensive.

It seems, if we want to continue to use the Wiki for doc development, we will need to clone the Wiki as a repository, add files to it, and check in the file. Even then, I am not sure if it will work correctly as evidenced in [@afig's Wiki page](https://github.com/DASSL/ClassDB/wiki/createRole()-User-Schema-checks-and-actions) on the flowchart related to Issue #136. See how the embedded image referencing a remote URL does not show up.

We need to urgently understand the underlying issues and learn workarounds/solutions so documentation does not become a problem.

Perhaps there is no issue at all, in which case, it will be helpful to confirm so before we get too far and then find a problem.

[KevinKelly25]

I took a look at [@afig's wiki page](https://github.com/DASSL/ClassDB/wiki/createRole()-User-Schema-checks-and-actions) and found that I could not use the URL link to the image that was embedded. I might be wrong, but there is a chance that it can just be google permissions not allowing the wiki page to access the image.

As for embedding images using markdown I found this help page which discusses adding images via markdown which might help.

So far, I have not found any work around for adding HTML files with MD. Most information I have seen about it suggests that MD only support a limited number of HTML tags. It may be that we can change ER-Schema to a MD file but wrap the code with ```. This won't display the HTML but until a work around is found it would allow all the files in the doc folder to be MD.

I was not here for the M1 development process so I might misunderstanding the issue but these might be temporary fixes.

[wildtayne]

I'm testing embedding images that are stored locally in the repository, and it seems to work with both the wiki and GitHub pages. I'll post a link when I have a more complete example of what does/doesn't work.

I also want to note that I also can't access the image @afig has linked on that page at all, even by going directly to the linked URL.

[wildtayne]

I've created a repository that uses both GitHub Pages and the Wiki to display the same page with content embedded using different methods. My findings are summarized below:

• Images can be embedded using img tags on both Pages and Wiki. Embedding local images always works, however embedding external images will likely run into cross-domain permissions errors (as @afig and I have both ran into when linking to Google Drive).

• Local HTML files can be embedded using iframes, however this only works in Pages. Wiki displays the iframe tag without rendering it for security reasons.

• Local HTML files can also be linked to using a tool I found, https://htmlpreview.github.io/?. This wraps the HTML file so it is rendered instead of showing the source. The only caveat I found with this method is that I could only get it to work by linking to a HTML file in the main repository, HTML files in the wiki repository would not load

[afig]

Thanks for the experimentation @srrollo, the embedded image on the initial wiki page that was created by me no longer worked for me as well. This specific issue seems to be caused by Google Drive no longer serving the image after a certain amount of time/number of requests, rather than an issue with GitHub's Wiki pages. Embedding an external image should still work.

I was also able to embed local images by cloning the Wiki as a repository, adding the file, and pushing the changes. The image of the flowchart is now located and hosted locally in the Wiki. Specifically, I created an img directory and placed the file in there. Within the wiki page, it is referenced as:

![Flowchart.png](img/UserandSchemaChecks.png)

Note that the image will not show up properly during preview, but will appear once the page is saved.

Ultimately, there should not be any issues with images during the docs-development process, but it might not be possible to easily embed or link to locally hosted non-image formats on a wiki page.

The main issue with hosting local HTML files is that GitHub wraps the file within another HTML page that forces the content to be displayed as text. (When served by GitHub pages, the wrapper is either not added, or is automatically removed.) The tool that @srrollo linked to removes extra wrapper, allowing the page to be rendered by the web browser. However, I noticed that the tool does not have a license associated with it. Moreover, that tool performs most of the work by using the Yahoo Query Language, so we may or may not have to attribute them as well.

[smurthys]

I think it will be helpful to add here a summary of the problem and the conclusion from yesterday's call.

[afig]

During the call, three main requirements were detailed by @smurthys for using the GitHub Wiki for the docs-development process:

1. Embed images into a wiki page, including locally hosted images
2. Host files within the same repository as the docs
3. Link to both internally and externally hosted files

From experimentation by @srrollo and myself, it was determined that:

1. Files can be hosted locally, and embedded into a wiki page. To add image files, the wiki repository must be cloned and then the image files checked in using a Git client. When embedding an image, the image does not appear in "preview" mode, but does appear once the page is saved.

2. "File hosting" works without issue for file types that are not .md or .html. .md files turn into wiki pages, as expected. .html files however are displayed as source when linked to.

3. Linking to files works without issues, and is performed similar to linking to another wiki page, but with an extension added. However, as mentioned above, linking to an HTML page results in the source being shown, rather than being rendered by the browser.

Cloning and working with the wiki Git repository is only necessary for adding new files. Page editing and linking to files can still be done using GitHub's interface.

---

Ultimately, it was decided that we would continue to use GitHub's Wiki for docs-development. Additionally, we will continue to store HTML versions of diagrams in the repo for version control purposes. We will later investigate switching to another format for creating/storing diagrams so as to not need to maintain .html files within the wiki Git repository.

I believe this issue can be closed for the time being. Later on, we will likely reevaluate the process, at least for creating diagrams.

[smurthys]

I propose we close this issue at the release of M2.