search

CONNECT-platform / codedoc

Create beautiful modern documentation websites.
https://codedoc.cc
MIT License
427 stars 12 forks source link

Storing images next to the referencing markdown #75

Open TysonMN opened 4 years ago

TysonMN commented 4 years ago

I currently store the markdown for my posts in one directory and the assets for those posts in another directory. However, I would prefer to store the assets unique to a particular post next to the markdown for that post. As an example, consider the directory structure containing the content of this non-coding.blog site. If I were to structure the content like that for my coding.blog site, I think I would have to add a path to the assets config key with each post. In contrast, I think adding a post to that other site only involves creating the markdown (example 1, example 2 part 1 part 2)...though maybe I am misunderstanding something there).

Is it possible to add new page to a CODEDOC site that references a locally stored image so that the markdown for that page and the image are stored near each other and also that no configuration changes are needed?

loreanvictor commented 4 years ago

This is not particularly a CODEDOC concern. When serving locally, CODEDOC serves any static file (and you need to address them typically by the root of your project, similar to markdown files). This is a hosting environment issue.

For example, for deploying to GitHub Pages, if you decide to put your build HTML files within your master branch, then you can similarly access all images with similar paths.

However if you follow this style, in which build files are moved to a separate folder, then the folder is put on gh-pages branch (without the rest of the repo being present), and then serving your GitHub Pages site from gh-pages branch, then you would need to somehow copy the images to that target folder as well (as they would need to end up in gh-pages branch too).

coding.blog behaves similar to that deployment, as it does NOT put all of your repo on the CDN, but rather only the build files built by CODEDOC. That is why you need to provide assets config key. However, you can for example put all the markdowns (and the images) in one folder, and pass that to assets. Now your markdown files and the images alongside them will be put on the CDN as well, and you can easily address them.

This solution however would not allow referring to images with a path relative to where the markdown file sits (as that is not where the built HTML file will sit). An alternative solution would be to build everything to . and then put . on the CDN (adding it to the assets), though I am unsure of how coding.blog's publish process would handle that (@must ideas?).

Another alternative would be a follow up to this issue, where you would be able to also specify parametric-ish path mappings, so that the build process would find your images and put each alongside the HTML file that requires it (however it does seem like a lot of trouble for a minor point of convenience on a particular folder structure).

must commented 4 years ago

As it works right now, we rely on the output of the build process and upload those built files (the html and specified asset files separately from the source files). This does impose some structure through CODEDOC but still allows for variations (i.e. the config). I am not sure if it would take the root folder into consideration once you add it to the assets list.

I agree with @loreanvictor that this enhancement would be a good way to solve this.

TysonMN commented 4 years ago

This is not particularly a CODEDOC concern. When serving locally, CODEDOC serves any static file (and you need to address them typically by the root of your project, similar to markdown files). This is a hosting environment issue.

I would prefer if the CODEDOC local server and the hosting environment had the same behavior when accessing a (potential) asset. I keep forgetting that they differ (so much). In particular, I only linked to the asset path given to coding-blog-plugin. I should have also linked to the asset path given to CODEDOC.

CODEDOC is concerned with the location of assets as shown by the asset config value. CODEDOC prepares the directory structure so that everything works when copied to a hosting environment. That is what made me think to create this issue in the CODEDOC repository.

This solution however would not allow referring to images with a path relative to where the markdown file sits (as that is not where the built HTML file will sit).

Does this assume that the path in the markdown and the HTML are the same? Is is possible to adjust paths to assets when converting the markdown to HTML? I would think so.

however it does seem like a lot of trouble for a minor point of convenience on a particular folder structure

I don't think it is a minor issue. I have encountered these thoughts before, both in me and in others, so I just wrote this blog post about it.

I want my blog writing experience to include as little friction as possible. Coding.blog is ridiculously good at this compared to anything that I have used before. Now that I am committed to coding.blog, I am looking for what friction it has.

There would be less friction if I could group my files semantically: one folder for each post containing all the files related to that post. I think I might be able to achieve that now if I am also willing to add a path for each post to the list of asset paths. However, my understanding is that this change would only have an effect on the deployed site, so I couldn't test it locally. (Eventually I will be able to test it in staging. c.f. https://github.com/CONNECT-platform/coding-blog/issues/31) Instead, my blog is currently groups its files syntactically: one folder for markdown and another folder for assets.

My eventual goal is to be able to add a post by only adding all files for that post in a single folder and editing no other files. This issue is about achieving the first part of that. At some point, I will create issues about how I can auto generate the cards for the five most recent posts and my archive page.

loreanvictor commented 4 years ago

hmmm ....

yeah maybe codedoc build process should copy some particular files located alongside markdown files alongside dest html files as well? this could perhaps resolve the issue in a really seamless way that is independent of the hosting environment config as well (though then we would have an additional layer for handling assets, one being coding.blog's own build process, the other being codedoc's build process).