Shortcode that pulls from separate sample source repo (docs concept convo continued)

support
1

@bep @moorereason @digitalcraftsman @budparr

This is an extension of the proposed docs source regorg.

I want to create a “code” shortcode for the new docs that at build pulls from a separate sample content repo and outputs the resulting <pre>/html using Hugo/Golang templating. This obviously won’t work with the way that Hugo currently creates content, so I’m wondering if there is a “hook”, makefile, whatever that you PROgrammers think could make this possible…

Let me expand since this is complicated. There would be two separate repos, for example:

repo 1: spf13/hugodocs
repo 2: spf13/samplesite

Let’s say that spf13/samplesite has the following structure:

content
  |__posts
      |--my-first-post.md (title = "My First Post")
      |--my-second-post.md (title = "My Second Post")
      |--my-third-post.md (title = "My Third Post")

Then let’s say we have a markdown content file for Hugo docs at spf13/hugodocs/functions/range.md (ignore the quality of the following content, please)…

---
title: range
date: 2017-01-01
publishdate: 2017-01-01
description: Blah blah yada yada...
---

`range` is blah blah blah and the full explanation of how to use range in templates yada yada yada.

{{% code in="layouts/index.html" out="index.html" %}}
    ```html
    <ul>
    {{ range where .Site.Pages "Section" "posts" }}
    <li>{{.Title}}</li>
    {{ end }}
    </ul>
    ```
{{% /code %}}

The important thing is that it would be really convenient if the HUGO templating within the code shortcode could be used ***and applied to the source from the sample docs site and then output as <pre>***…

This is an extension of a shortcode I have already created that outputs a code block with a “copy button” (you see this in a lot of newer docs; eg, Angular 2). Here is the source, and here it is in action:

https://ryans-agency-hugo-theme.netlify.com/theme-docs/#sortable-lists

The idea is that the finished docs would include sample layout and output for each function or feature that pulls from a single sample site repo filled with dummy content that represents some of the most common source organization (eg, posts, articles, tags/categories taxonomy, a couple data files, and a sample config).

I could create two separate shortcodes, one for the templating input and one of the final HTML output, but it would be more maintainable to have this pull automatically rather than manually copying and pasting between two different projects, especially as the sample site source is updated and new features/docs/mds are added to the documentation site.

So, referring back to the hugodocs/functions/range.md sample above, the following would be output at gohugo.io/docs/functions/range/index.html:

<!--head/header...-->
<h1>range</h1>
<p><code>range</code> is blah blah blah and the full explanation of how to use range in templates yada yada yada.</p>

<div class="code-block">
<h4 class="code-block-filename">layouts/index.html</h4>
  <button class="copy-code">COPY</button>
    <pre class="language-html">
      <code class="language-html">
        <ul>
        {{ range where .Site.Pages "Section" "posts" }}
          <li>{{.Title}}</li>
        {{ end }}
        </ul>
      </code>
    </pre>
</div>

<h2>Outputs to the following at <code>site.com/index.html</code></h2>

<pre class="language-html">
  <code class="language-html">
    <ul>
      <li>My First Post</li>
      <li>My Second Post</li>
      <li>My Third Post</li>
    </ul>    
  </code>
</pre>

<!--...footer,etc-->

It’s complex, so I’m open to suggestions…

2

And even the example is really incomplete since what I mentioned is just for what were previously called “list” pages. However, this wouldn’t work well for single page examples, unless the script also had a “find” for individuals files…

Maybe this is too complex to implement.

1 Like
3

I may be missing the point, @rdwatters, but wouldn’t it be possible to just make the Hugo/docs site an exemplary site itself from which to draw the examples?

4

Hmmm…how meta of you. I guess the the intention was to show a more common use case and keep it as simple as possible. There is still the question of writing a shortcode that takes in the code block but then actually executes it as templating and spits it out as yet another code block. Does that make sense?

Maybe there’s an obvious way to do this that I’m missing. There is also the question of whether the doc site itself represents all the functions, features, etc (e.g., working with data files).