You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Allow (or document how to create) structured folders for docs such that:
All images/articles can be contained within a single folder
Larecipe checks for both $path.md and $page/index.md (in that order) when trying to find renderable content
Can redirect to static content (or serve it up directly)
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
Each article is self-contained (making it easy to manage
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.
The text was updated successfully, but these errors were encountered:
Request
Allow (or document how to create) structured folders for docs such that:
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:
Note: I'm using the Diataxis framework for my documentation structure, but don't get too hung up on that.
Benefits
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.
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.
The text was updated successfully, but these errors were encountered: