TechDocs: Support README.md or docs/README.md to be treated as docs/index.md

[OrkoHunter]

Feature Suggestion

Add support for treating README.md or docs/README.md file as the index page for TechDocs (docs/index.md).

Possible Implementation

Before we run mkdocs build to generate a site, we already do some preprocessing here. Another step can be added here with the following flow

If `docs/index.md` is available, do nothing
Else duplicate `README.md` or `docs/README.md` as `docs/index.md`
Proceed

Context

A lot of projects have an existing README.md file which serves as an "index page" for those exploring the repository on GitHub/GitLab/etc. To add an index page on TechDocs, they need to create a separate docs/index.md file which is almost a duplicate of README sometimes. While some projects prefer these separate files for different use-cases, some also prefer to not having to duplicate README and index.md.

Risk

Note that usually README.md files are written in "GitHub flavoured markdown" while TechDocs/MkDocs use "Python flavoured markdown". There are only tiny bits of differences, like using * or - for bullet lists, etc.

[andrewthauer]

Note that usually README.md files are written in "GitHub flavoured markdown" while TechDocs/MkDocs use "Python flavoured markdown". There are only tiny bits of differences, like using * or - for bullet lists, etc.

My suggestion for this is to include mdx-truly-sane-lists in techdocs-core. This plugin is a saviour for dealing with the very annoying bullet differences in mkdocs vs commonmark / gf markdown.

[jrusso1020]

@andrewthauer just wanted to check but doesn't look like anyone has started on your suggestion. Would this just be something along the lines of adding this code to https://github.com/backstage/mkdocs-techdocs-core/blob/main/src/core.py#L107

config["markdown_extensions"].append("mdx_truly_sane_lists")

And the necessary dependency? here https://github.com/backstage/mkdocs-techdocs-core/blob/main/requirements.txt

Note that usually README.md files are written in "GitHub flavoured markdown" while TechDocs/MkDocs use "Python flavoured markdown". There are only tiny bits of differences, like using * or - for bullet lists, etc.

My suggestion for this is to include mdx-truly-sane-lists in techdocs-core. This plugin is a saviour for dealing with the very annoying bullet differences in mkdocs vs commonmark / gf markdown.

[andrewthauer]

I'm not aware of anyone else having looked at including this plugin. We are currently not using techdocs core directly, but adding the sane lists plugin would put us one step closer to being able to.

[jrusso1020]

I'm not aware of anyone else having looked at including this plugin. We are currently not using techdocs core directly, but adding the sane lists plugin would put us one step closer to being able to.

Opened up a PR in backstage/mkdocs-techdocs-core#41 @andrewthauer

[jmpage]

@camilaibs I noticed that you closed this issue, possibly because of the release of backstage/techdocs-container#21, resolving AndrewThauer's comment. It seems like the original issue raised by OrkoHunter regarding the inclusion of /README.md is still unresolved. Would it be reasonable to reopen this issue?

[matteosilv]

Hey guys I have the latest version of techdocs-cli 0.8.8 and the latest version of techdocs-core plugin 0.2.1. The fallback works if the README.md file is in the docs directory, but it doesn't it is in the root of the repository. I'm using it with the --no-docker option

[bautrey37]

Pinging since it's 2023 now. Could this issue be reopened?

Having the root README of the repository appear in the Techdocs would be very useful, as my org keeps lots of important information on this. Most people use these to view documentation on Github so it is not reasonable to move all of the documentation into the docs folder. Normally, if we don't have a docs folder, then the documentation is stored in the root README of the repository. Fixing this would improve the usability of Software Catelog components and improve searching for important text.

[alexef]

doesn't #11838 / https://github.com/backstage/backstage/pull/7080/files#diff-2660b7d30eeef02dfcd3db346b8c9baadb90758fdb1b1d5d7bf3f10761501fed address this?

[ChrisJBurns]

Can confirm, this doesn't work for me either.

With no docs/ folder I get:
ERROR - Config value 'docs_dir': The path '/private/var/folders/n3/vl2_0lg52_z6tyhs0sdt1qm40000gp/T/backstage-xLjwS6/docs' isn't an existing directory.

mkdocs.yml

site_name: 'new-new-service'
site_description: 'Main documentation for new-new-service'
repo_url: https://gitlab.com/....../new-new-service
edit_uri: edit/main

plugins:
  - techdocs-core

nav:
  - Overview:
    - What is new-new-service?: 'README.md'

The README.md is in the root directory as expected, but get no docs generated. If I was to docs/index.md I can see that can generated in the tech docs, but when trying to navigate to What is new-new-service? I get a 404.

[yogini-nemade]

Any update on this issue? Can README file be treated as docs/index.md?

[alexef]

We ended up using a UrlPreparer for the job:

export class MyUrlPreparer implements PreparerBase {
    private originalPreparer: UrlPreparer;
    private readonly logger: Logger;

    private constructor(preparer: UrlPreparer, logger: Logger) {
        this.originalPreparer = preparer;
        this.logger = logger;
    }

    static fromConfig(config: PreparerConfig): MyUrlPreparer {
        return new MyUrlPreparer(UrlPreparer.fromConfig(config), config.logger);
    }

    prepare(entity: Entity, options?: PreparerOptions | undefined): Promise<PreparerResponse> {
        return this.originalPreparer.prepare(entity, options).then((response) => {
            const docsPath = resolve(response.preparedDir, 'docs');
            this.logger.info("Running preparer")
            if (!fs.existsSync(docsPath)) {
                fs.mkdirSync(docsPath);
                options?.logger?.info(`Created missing docs directory ${docsPath}`)
                fs.copyFileSync(`${response.preparedDir}/README.md`, `${docsPath}/index.md`)
                options?.logger?.info(`Copied readme to ${docsPath}/index.md`)

                const mkdocs = {
                    "site_name": `${entity.metadata.name} README`,
                    "site_description": entity.metadata.description,
                    "docs_dir": "docs",
                    "repo_url": "",
                    "edit_url": ""
                }
                fs.writeFileSync(`${response.preparedDir}/mkdocs.yaml`, yaml.dump(mkdocs));
                options?.logger?.info(`Wrote standard ${docsPath}/mkdocs.yaml`)
            } else {
                this.logger.info("Docs folder exists, not doing anything.")
            }

            return response;
        })
    }
}

hooked in backend/src/plugins/techdocs.ts:

export default async function createPlugin(
  env: PluginEnvironment,
): Promise<Router> {
  // Preparers are responsible for fetching source files for documentation.
  const preparers = await Preparers.fromConfig(env.config, {
    logger: env.logger,
    reader: env.reader,
  });
  preparers.register('url', MyUrlPreparer.fromConfig({
    logger: env.logger,
    reader: env.reader,
  }))
...

[falkenbt]

As a simple workaround, I created a symlink inside the /docs directory:

ln -s ../README.md ./README.md

[asos-robbell]

Looks as though this may have already been implemented, although I'm struggling to find documentation:

#7080