Suggestion: make docfx to support to be included as a part in a site generated by other tools

[evil-shrike]

Make docfx to play well with other tools. I already have a static site generated by my toolset. And I want to include several areas with api doc generated by docfx. For example for TS and .NET APIs. Currently I have to customize docfx template heavily. I have to change templates, css, js. As docfx assets aren't at the site root, they are inside a area (like /client-api and /server-api). And I don't want docfx asset to be loaded twice from that subfolders. So have a folder with all docfx assets at the same level as api areas. It's just an example why I need to customize js (all such things are hard-coded inside js).

So in general I'd suggest to think about supporting such scenarios when docfx generates one or several subarea of some big static site that generated by other tool (or not generated, it can be some sort of CMS) .

[vicancy]

Hi @evil-shrike thanks for your suggestions.

For the scenario you mentioned, if client apis are saved to /api/client-api, server apis are saved to /api/server-api, while style files are in /api/styles, can that solve the issue loading twice?

[evil-shrike]

@vicancy well I guess it's not very important where styles are particularly located, it's about an ability to customize links to them. In my case I have the following structure:

/root -
  /assets - common assets
      /css
      /fonts
      /images
      /js
  /devel - dev version
      /api-client - api-doc built with docfx
      /api-server - api-doc built with docfx
      /casestudy - doc built with Assemble from *.md
      /client - doc built with Assemble from *.md
      /demos - demos browser app
      /docfx - common docfx assets
          docfx.css
          docfx.js
          docfx.vendor.js
          index.json
          lunr.min.js
          search-stopwords.json
          search-worker.js 
      /server - doc built with Assemble from *.md
      index.html
  /latest - latest released version, structure the same as in /devel
  /x.y.z  - previous version, structure the same as in /devel
  /release-noes - 
      index.html
      release-notes-x-y.html

[evil-shrike]

I'm not saying that currently it works badly, it's definitely possible to customize anything. But it requires extracting and overriding the template. It leads to the situation when it becomes pretty hard to upgrade docfx to newer versions. Because it implies pretty complex activities. Particularly we have to do the followings:

• compare original template to customized template
• understand what and why we changed
• extract template from a new version
• apply the same customization to it as before - but if and only if it's still makes sense. there could be some changes in template that makes our customization obsolete.

so it's not easy. That's because I'd prefer to minimize template customization or avoid it at all. It seems that it can be achieved via more rich configuration options. For example, template has scripts.tmpl.partial:

<script type="text/javascript" src="{{_rel}}styles/docfx.vendor.js"></script>
<script type="text/javascript" src="{{_rel}}styles/docfx.js"></script>
<script type="text/javascript" src="{{_rel}}styles/main.js"></script>
<script>hljs.initHighlightingOnLoad();</script>

I had to change it to:

<script type="text/javascript" src="../../assets/js/jquery.js"></script>
<script type="text/javascript" src="../../assets/js/bootstrap.min.js"></script>
<script type="text/javascript" src="../../assets/js/highlight.pack.js"></script>
<script>hljs.initHighlightingOnLoad();</script>
<script type="text/javascript" src="../../assets/js/docpage.js"></script>
<script type="text/javascript" src="../docfx/docfx.js"></script>
<script type="text/javascript" src="../docfx/docfx.vendor.js"></script>

Would be it easier if we could specify scripts in docfx.json?

[vicancy]

Yes @evil-shrike I agree with you. Current template system exposes the entire html DOM, it sounds flexible, however it is too flexible that it is hard to maintain. We are in a way to rephrase the experience in v3.0 (with breaking changes). The initial idea is to hide the html DOM but provide rich options to customize the template. It is still in very early stage, and please feel free to provide your ideas and thoughts.