Help needed with custom OutputFormat

support
1

Hello everyone.
I’m currently building a site for my iOS app for which I need to write, among other things, some documentation. In my content folder, I created a /docs/ subfolder. In this subfolder, I’ve created an _index.md and other files like introduction.md and other.md:

/contents
    /docs
        _index.md
        introduction.md
        other.md

I would like the documentation to be accessible on the web, but also “almost” natively from the app, i.e. without the header and footer from the webpage. I’ve defined an OutputFormat called app in config.toml:

[outputFormats]
  [outputFormats.app]
    mediaType = "text/html"
    path = "/app"

I would like to apply custom templates and css to this html format and access it like /docs/ but at /app/docs/, but I’m facing two issues:

Firstly, `/app/ is generated with the structure

/app
    /docs
        introduction/
            index.html
        other/
            index.html

No trace of index.html to represent the _index.md of docs. However, in the root (web) `/docs/, I have

/docs
    index.html
    app/
        index.html
    introduction/
        index.html
    other/
        index.html

I don’t understand why there is an app subfolder here, and why there is no index.html in /app/docs/ in the root. Does anyone have an explanation?

The second issue I’m facing is the way to link content. Let say I’m creating a reference to other.md from introduction.md. I would like the output format to be preserved, that is linking to /docs/other/index.html in the web version, and /app/docs/other/index.html in the app version.
I’ve tried the shortcode {{< ref "docs/other.md" >}} but it always resolve to the web version /docs/other/index.html, even for the app version. How to properly link content in this case?

I’m using a custom template with

layouts/
    /_default
        baseof.app.html
        baseof.html
        list.html
        page.html
        single.hml
    /docs
        baseof.html
        list.html
        page.html
        single.hml

All my markdown files have layout: "page" in the front-matter and I’ve defined

[outputs]
  page = ["HTML", "APP"]
  section = ["HTML", "APP", "RSS"]

in config.toml.

Thank you in advance!

2 
/docs
    index.html
    app/
        index.html

The first index comes from HTML output, the second from APP output.

Quote: Paths without a leading / will first be tried resolved relative to the current page.
{{< ref "docs/other.md" >}} should be {{< ref "/docs/other.md" >}}

and you can add “outputFormat” “app”

{{< ref "/docs/other.md" "outputFormat" "app">}}

set in

[outputFormats.app]
   isHTML = true
   permalinkable = true
3

Thank your for your answer

While I can understand that docs/app/index.html comes from the APP output, I don’t understand why it is here and not at /app/docs/index.html beside the other versions of Introduction and Other. I would like to access the app version of the docs at /app/docs/index.html. Right now, I need to point at /docs/app/index.html while the rest of the content is at /app/docs/introduction/, etc.

So my question resumes to: what should I change so the app version of content/docs/_index.md generates at /app/docs/index.html?

For the links, if I link {{< relref "/docs/other.md" "outputFormat" "app">}}, it works only for the app version and point to the wrong file in the web version. I don’t know if it is doable with built-in functions, but I feel I can write a custom shortcode to handle this ultimately.

4

1st remove HTML from the [output] section and try to fix all *app things.
2nd activate HTML and remove APP to resolve the rest.

Can you create a sample repository?

5

Thanks for the tip of removing HTML from [output]. No matter what I try, Hugo generates a /doc/app/index.html for the branch /docs/_index.md. If I rename it /docs/index.md, it goes at the correct location /app/docs/index.html, but it breaks the /docs/ web version. I resorted to use custom prefixes instead of custom path and it works now for me. I still don’t know why output formats of branch bundles is different from leaf bundles. Maybe I’ll investigate later.

I’ve also written a custom ShortCode with an app override to handle the links.

Thanks again for your feedback.