How to use project's root README.md as index.md

[senketsu03]

I'm sorry I have to ask this question, but I haven't found an answer and I couldn't figure it out myself.

I have the following project folder structure:

_docs
Application
Library
Tests
docs
Resources
CHANGELOG.md
docfx.json
LICENSE.md
README.md

The docfx.json file contents:

{
  "metadata": [
    {
      "src": [
        {
          "files": ["Library/**.csproj"],
          "exclude": ["**/bin/**", "**/obj/**"]
        }
      ],
      "dest": "_docs/api",
      "includePrivateMembers": false,
      "disableGitFeatures": false,
      "disableDefaultFilter": false,
      "noRestore": false,
      "namespaceLayout": "flattened",
      "memberLayout": "samePage",
      "allowCompilationErrors": false
    }
  ],
  "build": {
    "content": [
      {
        "files": ["**"],
        "src": "_docs/api",
        "dest": "api"
      },
      {
        "files": ["articles/**.md", "articles/**/toc.yml", "toc.yml", "*.md"],
        "src": "_docs"
      }
    ],
    "resource": [
      {
        "files": ["**"],
        "src": "Resources",
        "dest": "images"
      }
    ],
    "globalMetadata": {
      "_appFaviconPath": "images/Icon.ico",
      "_appLogoPath": "images/Icon.png"
    },

    "output": "docs",
    "globalMetadataFiles": [],
    "fileMetadataFiles": [],
    "template": ["default", "modern"],
    "postProcessors": [],
    "keepFileLink": false,
    "disableGitFeatures": false
  }
}

And _docs/toc.yml:

- name: Home
  href: index.md
- name: Library
  href: api/toc.yml
  homepage: articles/core-index.md
- name: Cli
  href: articles/cli-index.md
- name: Tests
  href: articles/tests-index.md

Right now I'm building docs with a script:

cp README.md _docs/index.md

# I reference LICENSE from my README, so it throws warning on docfx build if it's not copied manually
cp LICENSE.md _docs/LICENSE.md

docfx metadata
docfx build
docfx serve

But this doesn't seem like a good approach for using README as index page. Is it somehow possible to do through docfx.json?
Plus, for unknown reason, when I look at page on my localhost, it doesn't automatically loads index.md, it loads the project directory first, so I have to navigate to docs folder to see the website. How can this be fixed?

[merlinschumacher]

I'm actually wondering the same thing

[patrickserrano]

Has anyone figured this out?

[filzrev]

But this doesn't seem like a good approach for using README as index page. Is it somehow possible to do through docfx.json?

As far as I knows. There is no such functionality on docfx.
It need to copy files manually as pre-processing.

Plus, for unknown reason, when I look at page on my localhost, it doesn't automatically loads index.md, it loads the project directory first,

docfx serve command is not use docfx.json settings.
It simply launch web server on current directory.

So It need to specify site directory (e.g. docfx serve _site)
Or try to use docfx build --serve command instead.

[ShortDevelopment]

As seen in this Test, you can simply prepend your *.md file with a frontmatter block

docfx/test/Docfx.Build.Tests/ConceptualDocumentProcessorTest.cs

Lines 162 to 164 in 0cceb23

	var file1 = _fileCreator.CreateFile($@"---
	outputFileName: {renameFile1}
	---

---
outputFileName: index.html
---

# My cool project
Your `README.md` content

[calacayir]

Using README.md in your docs:

• When you want to reference your repository's README.md file, you can create index.md next to docfx.json with contents:

  [!include [getting-started](../README.md)]
  

  Note that upper case !INCLUDE as noted in docs, may not work on some machines (probably due to turkish-I bug in docfx).
  The path should be relative to the containing file.
  index.md needs to exist anyway otherwise homepage (/) will not work so it's better to include README.md in this file
  if there is nothing else to put on the homepage.

• Another way: if you define external .md files as content in docfx.json like this:

  "build": {
    "content": [
      {
        "files": ["README.md"],
        "src": "../",
        "dest": "docs"
      }
    ],
  

  dot-dot notation can not appear in files but it can appear in src.
  src is relative to the docfx.json folder (config root).
  The dest means the output subfolder (under _site by default) for the corresponding html file, e.g. README.html.

  Then in toc.yml you can reference the .md file:

  - name: Readme
    href: ~/../README.md
  - name: Prerequisites
    href: ~/../README.md#prerequisites
  

  Note that the path should match src and not dest. Using ~/ in case toc.yml is in a subfolder and not in config root.
  You can also put the # fragment but the file will not be splitted, it will just be a fragment link.

https://github.com/dotmake-build/docfx-plus#using-readmemd-in-your-docs