# Help needed with custom OutputFormat

**URL:** <https://discourse.gohugo.io/t/help-needed-with-custom-outputformat/24680>\
**Category:** support\
**Created:** [April 12, 2020, 9:28am UTC](https://discourse.gohugo.io/t/help-needed-with-custom-outputformat/24680 "2020-04-12T09:28:29Z")\
**Posts on this page:** 5\
**Page:** 1

<div class="post-metadata">

**Author:** ![tomette](https://avatars.discourse-cdn.com/v4/letter/t/6f9a4e/32.png) [@tomette](https://discourse.gohugo.io/u/tomette)\
**Post date:** [April 12, 2020, 9:28am UTC](https://discourse.gohugo.io/t/help-needed-with-custom-outputformat/24680/1 "2020-04-12T09:28:29Z")

</div>

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`:

```auto
/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`:

```auto
[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

```auto
/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

```auto
/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

```auto
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

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

```

in `config.toml`.

Thank you in advance!

---

<div class="post-metadata">

**Author:** ![ju52](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/ju52/32/6749_2.png) [@ju52](https://discourse.gohugo.io/u/ju52)\
**Post date:** [April 12, 2020, 12:54pm UTC](https://discourse.gohugo.io/t/help-needed-with-custom-outputformat/24680/2 "2020-04-12T12:54:59Z")

</div>

```
/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">}}`

> **[Links and Cross References](https://gohugo.io/content-management/cross-references/#get-another-output-format)**
>
> Shortcodes for creating links to documents.

set in

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

```

> **[Custom Output Formats](https://gohugo.io/templates/output-formats/#configure-output-formats)**
>
> Hugo can output content in multiple formats, including calendar events, e-book formats, Google AMP, and JSON search indexes, or any custom text format.

---

<div class="post-metadata">

**Author:** ![tomette](https://avatars.discourse-cdn.com/v4/letter/t/6f9a4e/32.png) [@tomette](https://discourse.gohugo.io/u/tomette)\
**Post date:** [April 12, 2020, 3:00pm UTC](https://discourse.gohugo.io/t/help-needed-with-custom-outputformat/24680/3 "2020-04-12T15:00:36Z")

</div>

Thank your for your answer

> [@ju52](#):
>
> The first index comes from HTML output, the second from APP output.

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.

---

<div class="post-metadata">

**Author:** ![ju52](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/ju52/32/6749_2.png) [@ju52](https://discourse.gohugo.io/u/ju52)\
**Post date:** [April 12, 2020, 3:13pm UTC](https://discourse.gohugo.io/t/help-needed-with-custom-outputformat/24680/4 "2020-04-12T15:13:14Z")

</div>

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?

---

<div class="post-metadata">

**Author:** ![tomette](https://avatars.discourse-cdn.com/v4/letter/t/6f9a4e/32.png) [@tomette](https://discourse.gohugo.io/u/tomette)\
**Post date:** [April 13, 2020, 11:34am UTC](https://discourse.gohugo.io/t/help-needed-with-custom-outputformat/24680/5 "2020-04-13T11:34:57Z")

</div>

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.