Structuring Content w/index.md and static content

[dfidler]

Request

Allow (or document how to create) structured folders for docs such that:

1. All images/articles can be contained within a single folder
2. Larecipe checks for both $path.md and $page/index.md (in that order) when trying to find renderable content
3. Can redirect to static content (or serve it up directly)
4. Put static content behind the auth provider

Background

I might be doing something wrong but I can't seem to get Larecipe + nginx to serve up my files in an easy-to-write/organize framework.

My challenges are that my doc writers are not programmers and they are using wysiwyg markdown editors and that spells disaster for creating the content because larecipe seems to require users to host renderable md content separately from static content.

Proposed Solution

I would like to be able to host my static files WITH my markdown content so image tags can easily reference screenshots relative to the markdown.

As an example, my folder structure for docs is as follows:

{{version}}/
    explanation/
        seo_article_name_1/
        seo_article_name_2/
    howto/
        category1/
            index.md                # list of sub articles
            seo_article_name_1/    # an article about something with markdown + images
                index.md            # the markdown
                {{uuid}}.png
                {{uuid}}-02.jpg
        seo_article_name_2/ ...
  reference/  ...
  tutorial/ ...

Note: I'm using the Diataxis framework for my documentation structure, but don't get too hung up on that.

Benefits

1. Each article is self-contained (making it easy to manage
2. Image tags in the markdown no longer need {{route}} or any other variables (making it wysiwyg editor friendly)

Alternatives Considered

Configure nginx to find static files first

This might still be an alternative but it will quickly become very complex.

Issue: How can I put the static files behind auth?
Answer: I can't. I can only obfuscate filenames (which I started doing already, using UUIDs for filenames to prevent brute-force downloads of files

But it would reduce the load on my app if it didn't have to serve the files. However, serving small image files isn't going to bring my app to a halt.

Use a build script

I could have my doc team write wysiwyg markdown and then use a build script to rewrite the docs files and put them in a statically linked directory.

However, I'm loathe to do that as that's one more thing we need to maintain.

Additional context

Larecipe Version: 2.6.1

Note: I've already implemented a proof of concept for this in my own environment and wanted to find out if people had other suggestions or if others would find this useful.

### src/Models/Documentation.php: v2.6.1

    public function get($version, $page, $data = [])
    {
        return $this->cache->remember(function() use($version, $page, $data) {           
            $paths = [  
                base_path(config('larecipe.docs.path').'/'.$version.'/'.$page.'.md'),        # find the md file
                base_path(config('larecipe.docs.path').'/'.$version.'/'.$page.'/index.md'),  # look inside a directory for index.md
            ];

            foreach ($paths as $path) {
                if ($this->files->exists($path)) {
                    $parsedContent = $this->parse($this->files->get($path));

                    $parsedContent = $this->replaceLinks($version, $parsedContent);

                    return $this->renderBlade($parsedContent, $data);
                }
            }

            // does the file exist on the filesystem?
            $path = base_path(config('larecipe.docs.path').'/'.$version.'/'.$page);
            // $fname = array_slice(explode('/', $path), -1);
            $x = $this;

            if ($this->files->exists($path)) {
                return response()->stream( function() use ($path, $x) {
                    echo $x->files->get($path);
                })->send();
            }

            return null;
        }, 'larecipe.docs.'.$version.'.'.$page);
    }

This code isn't bulletproof and needs some love, but it at least works.

Is this something that the project would like to pursue? If so, I'm happy to do more work on it and the PR it.