Change config to be a json file

[Relequestual]

Other applications or tools may want to write to the configuration file provided. They may also want to read from it using another language!

It sure would be easier if it was json a json file.

[handrews]

@Relequestual are you talking about this config file? https://github.com/cloudflare/doca/blob/master/app/config.js

[tajo]

@Relequestual You can use a custom json file and reexport it in config.js.

I prefer JS configs over json because of flexibility.

[handrews]

I prefer JS configs over json because of flexibility.

@tajo can you elaborate? Is this "JSON doesn't have comments and JavaScript does" kind of flexibility, or is this "I want to be able to stuff running code in the config file"?

[Relequestual]

You can use a custom json file and reexport it in config.js.

I don't know what you mean by this. Can you explain? =]

I want to be able to manage my json file from perl, because that's where the information I need will be located. Currently I'm editing it manually, which isn't maintainable in the long run.

[tajo]

@tajo can you elaborate? Is this "JSON doesn't have comments and JavaScript does" kind of flexibility, or is this "I want to be able to stuff running code in the config file"?

Both. :) All FE tools have JS configs now. Sometimes it's really helpful for things like "list all files in this directory".

I don't know what you mean by this. Can you explain? =]

config.json

{
  "foo": "xxx"
}

config.js

import config from './config.json';
export default config;

[handrews]

This comes down to what level of accessibility we want to provide for non-JavaScript environments, as doca is not exclusively used from front-end JavaScript code. I'm OK with JS things that are only used from within JS having JS configurations, but doca has an external interface.

If we actually need a JavaScript config because of a need to run code, then I would like to see a standard mechanism for non-JS systems to work with a JSON file, and then merge that into a JS file in a well-defined way.

[Relequestual]

@tajo OH, OK.

I do agree with @handrews assessment though. Currently there's no evidence of code running as part of the config (it's all static). If there's a good use case, then fine by me, assuming we address the issue @handrews raises.

[Relequestual]

I wanted to load some markdown text into the top section of the resulting documentation as an introduction. I can use MarkdownPreview (already included) and node module markdown-toc to update the menu. However loading the markdown content into the config from a file is not so easy.

---

I tried to load in some markdown content from a file into the config. Turns out this is more difficult that I assumed, and I probably have some missunderstandings as to how things work.

Loading content from a file requires the core module fs, which means it can't then run on the front end only, because if webpack config target is set to node, require is then undefined. I imagine there's a whole host of other related problems around this.

It looks like my only option for now is to leave some placeholders in the configuration file, and then sed -i replace the placeholders with the contense of my markdown files... seems a little cack-handed, but I can't see any other viable options.

[tajo]

@Relequestual sounds like something that markdown-loader would be great for.

[Relequestual]

No idea how I would even start using that. Why don't their examples actually show you how to use it rather than assuming so much?

I've spent today trying to get the titles from my markdown into the sidebar. DO NOT try to use markdown-toc with webpack, it's all but impossible. There are people who claim they have made it work. I have tried. It does not. I cannot. I tried using unlazy in the webpack config, not loading fs, and eventually reached an impass where I get an error Cannot find module "querystring". I found others who had the same issue, had a resolution, but it didn't work for me.

markdown-toc uses lazy-cache, which claims there is a bug with webpack which causes this (overall) issue. I'm just going to parse and extract the titles myself =/

If you try to do this and have any luck, let me know, but I've reached the end of the day with no progress so as you can probably guess, I'm not too happy with the whole webpack thing right now.

[tajo]

markdown-loader outputs html, so you need to chain it with html-loader (to get a module) and then you can do something like this

import text from './text.md';

// React component
export default () =>
  <div dangerouslySetInnerHTML={{__html: text }} />

[Relequestual]

Interesting. I'm going to continue to load the markdown now as I want to use it to generate additional menu items, but that's useful to know, thanks.

[Relequestual]

Sorry this issue has turned into a bit of a discussion thread... It's a shame we don't have a doca slack (even if it would be low traffic) to avoid cluttering issues =]

[handrews]

@tajo @Relequestual

• For things that could be contributed back to json-schema-org/json-schema-spec#136 (JSON Schema docs vocabulary), they should be moved out of the config file and into the schemas, and be given a proper meta-schema description

• For configuring the behavior of the JavaScript code, those things should stay in config.js, which should stay JavaScript and not JSON for the reasons @tajo notes. @Relequestual I think that should work for you as the things remaining in config.js should not be particularly relevant to other languages.

[Relequestual]

Fair enough. In which case, my question is where do you locate your documentation content which is static text but not part of the JSON Schema file? Like the introduction section. Including it in the theme doesn't lend well to swapping themes in and out, and I don't see an alternative.

[handrews]

Internally, our theme (as of recently) has a hook for intro text. Let's file an issue for that and close this one out as it's gotten quite muddled.

[handrews]

@Relequestual Oh actually that fix was in the doca scaffolding project not the theme so it's already available to everyone. If you scaffold a new app, there is now an introduction.js React component with placeholder text and instructions to modify. So I think this is all now addressed.