Generate index.md from README.md

Author: AndreyAkinshin

README.md

@@ -1,38 +1,37 @@
-<h3 align="center">
+<div align="center">
 
-  ![](docs/logo/logo-wide.png)
+  ![](https://raw.githubusercontent.com/dotnet/BenchmarkDotNet/ec962b0bd6854c991d7a3ebd77037579165acb36/docs/logo/logo-wide.png)
 
-</h3>
+</div>
 
-<h3 align="center">
+<div align="center">
 
   [![NuGet](https://img.shields.io/nuget/v/BenchmarkDotNet.svg)](https://www.nuget.org/packages/BenchmarkDotNet/)
   [![Downloads](https://img.shields.io/nuget/dt/benchmarkdotnet.svg)](https://www.nuget.org/packages/BenchmarkDotNet/)
   [![Stars](https://img.shields.io/github/stars/dotnet/BenchmarkDotNet?color=brightgreen)](https://github.com/dotnet/BenchmarkDotNet/stargazers)
-  [![Gitter](https://img.shields.io/gitter/room/dotnet/BenchmarkDotNet?color=yellow)](https://gitter.im/dotnet/BenchmarkDotNet)
-  [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.md)
-  [![Twitter](https://img.shields.io/twitter/follow/BenchmarkDotNet?style=social)](https://twitter.com/BenchmarkDotNet)
+  ![License](https://img.shields.io/badge/license-MIT-blue.svg)
+  [![Twitter](https://img.shields.io/twitter/follow/BenchmarkDotNet?style=social&label=Twitter)](https://twitter.com/BenchmarkDotNet)
 
-</h3>
+</div>
 
-<h3 align="center">
+<div align="center" style="font-size: 130%; margin-bottom: 20px">
   <a href="#features">Features</a>
   <span> · </span>
   <a href="https://benchmarkdotnet.org/articles/guides/getting-started.html">Getting started</a>
   <span> · </span>
   <a href="https://benchmarkdotnet.org/articles/overview.html">Documentation</a>
   <span> · </span>
   <a href="#learn-more-about-benchmarking">Learn more about benchmarking</a>
-</h3>
+</div>
 
 **BenchmarkDotNet** helps you to transform methods into benchmarks, track their performance, and share reproducible measurement experiments.
 It's no harder than writing unit tests!
 Under the hood, it performs a lot of [magic](#automation) that guarantees [reliable and precise](#reliability) results thanks to the [perfolizer](https://github.com/AndreyAkinshin/perfolizer) statistical engine.
 BenchmarkDotNet protects you from popular benchmarking mistakes and warns you if something is wrong with your benchmark design or obtained measurements.
 The results are presented in a [user-friendly](#friendliness) form that highlights all the important facts about your experiment.
-The library is adopted by [16500+ GitHub projects](#who-uses-benchmarkdotnet) including .NET Runtime and supported by the [.NET Foundation](https://dotnetfoundation.org).
+The library is adopted by [16500+ GitHub projects](#who-uses-benchmarkdotnet) including .NET Runtime.
 
-It's [easy](#simplicity) to start writing benchmarks, check out an example
+It's [easy](#simplicity) to start writing benchmarks, check out the following example
   (copy-pastable version is [here](https://benchmarkdotnet.org/articles/guides/getting-started.html)):
 
 ```cs
@@ -106,7 +105,7 @@ Intel Core i7-7700K CPU 4.20GHz (Kaby Lake), 1 CPU, 8 logical and 4 physical cor
 
 The measured data can be exported to different formats (md, html, csv, xml, json, etc.) including plots:
 
-![](docs/images/v0.12.0/rplot.png)
+![](https://raw.githubusercontent.com/dotnet/BenchmarkDotNet/ec962b0bd6854c991d7a3ebd77037579165acb36/docs/images/v0.12.0/rplot.png)
 
 *Supported runtimes:* .NET 5+, .NET Framework 4.6.1+, .NET Core 2.0+, Mono, NativeAOT  
 *Supported languages:* C#, F#, Visual Basic  
@@ -128,7 +127,7 @@ For example, if you want to [parameterize](https://benchmarkdotnet.org/articles/
   mark a field or a property with `[Params(1, 2, 3)]`: BenchmarkDotNet will enumerate all of the specified values
   and run benchmarks for each case.
 If you want to compare benchmarks with each other,
-  mark one of the benchmark as the [baseline](https://benchmarkdotnet.org/articles/features/baselines.html)
+  mark one of the benchmarks as the [baseline](https://benchmarkdotnet.org/articles/features/baselines.html)
   via `[Benchmark(Baseline = true)]`: BenchmarkDotNet will compare it with all of the other benchmarks.
 If you want to compare performance in different environments, use [jobs](https://benchmarkdotnet.org/articles/configs/jobs.html).
 For example, you can run all the benchmarks on .NET Core 3.0 and Mono via
@@ -158,12 +157,12 @@ If you prefer command-line experience, you can configure your benchmarks via
 
 Reliable benchmarks always include a lot of boilerplate code.
 
-Let's think about what should you do in a typical case.
+Let's think about what you should do in a typical case.
 First, you should perform a pilot experiment and determine the best number of method invocations.
 Next, you should execute several warm-up iterations and ensure that your benchmark achieved a steady state.
 After that, you should execute the main iterations and calculate some basic statistics.
-If you calculate some values in your benchmark, you should use it somehow to prevent the dead code elimination.
-If you use loops, you should care about an effect of the loop unrolling on your results
+If you calculate some values in your benchmark, you should use it somehow to prevent dead code elimination.
+If you use loops, you should care about the effect of the loop unrolling on your results
   (which may depend on the processor architecture).
 Once you get results, you should check for some special properties of the obtained performance distribution
   like multimodality or extremely high outliers.
@@ -174,7 +173,7 @@ If you write this code from scratch, it's easy to make a mistake and spoil your
 Note that it's a shortened version of the full checklist that you should follow during benchmarking:
   there are a lot of additional hidden pitfalls that should be handled appropriately.
 Fortunately, you shouldn't worry about it because
-  BenchmarkDotNet [will do](https://benchmarkdotnet.org/articles/guides/how-it-works.html) this boring and time-consuming stuff for you.
+  BenchmarkDotNet [will perform](https://benchmarkdotnet.org/articles/guides/how-it-works.html) this boring and time-consuming stuff for you.
 
 Moreover, the library can help you with some advanced tasks that you may want to perform during the investigation.
 For example,
@@ -193,10 +192,10 @@ You shouldn't worry about the perfect number of method invocation, the number of
 So, you shouldn't use any magic numbers (like "We should perform 100 iterations here"),
   the library will do it for you based on the values of statistical metrics.
 
-BenchmarkDotNet also prevents benchmarking of non-optimized assemblies that was built using DEBUG mode because
+BenchmarkDotNet also prevents benchmarking of non-optimized assemblies that were built using DEBUG mode because
   the corresponding results will be unreliable.
-It will print a warning you if you have an attached debugger,
-  if you use hypervisor (HyperV, VMware, VirtualBox),
+The library will print a warning if you have an attached debugger,
+  if you use a hypervisor (HyperV, VMware, VirtualBox),
   or if you have any other problems with the current environment.
 
 During 6+ years of development, we faced dozens of different problems that may spoil your measurements.
@@ -224,7 +223,7 @@ In this case, you can scroll the results up and check out ASCII-style histograms
   or generate beautiful png plots using `[RPlotExporter]`.
 
 BenchmarkDotNet doesn't overload you with data; it shows only the essential information depending on your results:
-  it allows you to keep summary small for primitive cases and extend it only for the complicated cases.
+  it allows you to keep the summary small for primitive cases and extend it only for complicated cases.
 Of course, you can request any additional statistics and visualizations manually.
 If you don't customize the summary view,
   the default presentation will be as much user-friendly as possible. :)
@@ -270,7 +269,7 @@ BenchmarkDotNet is already adopted by more than [16500+](https://github.com/dotn
 ## Learn more about benchmarking
 
 BenchmarkDotNet is not a silver bullet that magically makes all of your benchmarks correct and analyzes the measurements for you.
-Even if you use this library, you still should know how to design the benchmark experiments and how to make correct conclusions based on the raw data.
+Even if you use this library, you still should know how to design benchmark experiments and how to make correct conclusions based on the raw data.
 If you want to know more about benchmarking methodology and good practices,
   it's recommended to read a book by Andrey Akinshin (the BenchmarkDotNet project lead): ["Pro .NET Benchmarking"](https://aakinshin.net/prodotnetbenchmarking/).
 Use this in-depth guide to correctly design benchmarks, measure key performance metrics of .NET applications, and analyze results.
@@ -287,11 +286,11 @@ You will avoid common pitfalls, control the accuracy of your measurements, and i
 
 | Build server | Platform | Build status |
 |--------------|----------|--------------|
-| Azure Pipelines | Windows | [![Azure Pipelines Windows](https://dev.azure.com/dotnet/BenchmarkDotNet/_apis/build/status/BenchmarkDotNet%20-%20Windows)](https://dev.azure.com/dotnet/BenchmarkDotNet/_build/latest?definitionId=55) |
-| Azure Pipelines | Ubuntu  | [![Azure Pipelines Ubuntu](https://dev.azure.com/dotnet/BenchmarkDotNet/_apis/build/status/BenchmarkDotNet%20-%20Ubuntu)](https://dev.azure.com/dotnet/BenchmarkDotNet/_build/latest?definitionId=56) |
-| Azure Pipelines | macOS | [![Azure Pipelines macOS](https://dev.azure.com/dotnet/BenchmarkDotNet/_apis/build/status/BenchmarkDotNet%20-%20macOS)](https://dev.azure.com/dotnet/BenchmarkDotNet/_build/latest?definitionId=57) |
+| Azure Pipelines | Windows | [![Azure Windows](https://dev.azure.com/dotnet/BenchmarkDotNet/_apis/build/status/BenchmarkDotNet%20-%20Windows)](https://dev.azure.com/dotnet/BenchmarkDotNet/_build/latest?definitionId=55) |
+| Azure Pipelines | Ubuntu  | [![Azure Ubuntu](https://dev.azure.com/dotnet/BenchmarkDotNet/_apis/build/status/BenchmarkDotNet%20-%20Ubuntu)](https://dev.azure.com/dotnet/BenchmarkDotNet/_build/latest?definitionId=56) |
+| Azure Pipelines | macOS | [![Azure macOS](https://dev.azure.com/dotnet/BenchmarkDotNet/_apis/build/status/BenchmarkDotNet%20-%20macOS)](https://dev.azure.com/dotnet/BenchmarkDotNet/_build/latest?definitionId=57) |
 | AppVeyor | Windows | [![AppVeyor/Windows](https://img.shields.io/appveyor/ci/dotnetfoundation/benchmarkdotnet/master.svg)](https://ci.appveyor.com/project/dotnetfoundation/benchmarkdotnet/branch/master) |
-| GitHub Actions | * | [![build](https://github.com/dotnet/BenchmarkDotNet/actions/workflows/build.yaml/badge.svg)](https://github.com/dotnet/BenchmarkDotNet/actions/workflows/build.yaml) |
+| GitHub Actions | * | [![GitHub Actions](https://github.com/dotnet/BenchmarkDotNet/actions/workflows/build.yaml/badge.svg)](https://github.com/dotnet/BenchmarkDotNet/actions/workflows/build.yaml) |
 
 ## Contributions are welcome!
 
@@ -309,6 +308,6 @@ Let's build the best tool for benchmarking together!
 
 ## Code of Conduct
 
-This project has adopted the code of conduct defined by the [Contributor Covenant](http://contributor-covenant.org/)
+This project has adopted the code of conduct defined by the [Contributor Covenant](https://www.contributor-covenant.org/)
 to clarify expected behavior in our community.
 For more information, see the [.NET Foundation Code of Conduct](https://dotnetfoundation.org/code-of-conduct).

build/Program.cs

@@ -162,7 +162,7 @@ public void EnsureChangelogDetailsExist(bool forceClean = false)
         var path = ChangeLogGenDirectory.Combine("details");
         if (this.DirectoryExists(path) && forceClean)
             this.DeleteDirectory(path, new DeleteDirectorySettings() { Force = true, Recursive = true });
-        
+
         if (!this.DirectoryExists(path))
         {
             var settings = new GitCloneSettings { Checkout = true, BranchName = "docs-changelog-details" };
@@ -475,7 +475,7 @@ public override void Run(BuildContext context)
     {
         var count = context.Argument("VersionCount", -1);
         var total = DocumentationHelper.BdnAllVersions.Length;
-        
+
         if (count == 0)
         {
             context.DocfxChangelogDownload(
@@ -569,6 +569,14 @@ public class DocfxBuildTask : FrostingTask<BuildContext>
 {
     public override void Run(BuildContext context)
     {
+        context.Information("DocfxBuild: Generate index.md");
+        var content = new StringBuilder();
+        content.AppendLine("---");
+        content.AppendLine("title: Home");
+        content.AppendLine("---");
+        content.Append(context.FileReadText(context.RootDirectory.CombineWithFilePath("README.md")));
+        context.FileWriteText(context.DocsDirectory.CombineWithFilePath("index.md"), content.ToString());
+
         context.RunDocfx(context.DocfxJsonFile);
         context.GenerateRedirects();
     }
@@ -636,8 +644,7 @@ public override void Run(BuildContext context)
         };
         var files = new[]
         {
-            context.RootDirectory.CombineWithFilePath("README.md"),
-            context.DocsDirectory.CombineWithFilePath("index.md")
+            context.RootDirectory.CombineWithFilePath("README.md")
         };
         foreach (var file in files)
         {
@@ -648,7 +655,7 @@ public override void Run(BuildContext context)
                     lines[i] = updater.Apply(lines[i]);
             }
 
-            context.FileWriteLines(file, lines);   
+            context.FileWriteLines(file, lines);
         }
     }
-}
+}

docs/.gitignore

@@ -10,4 +10,5 @@ _site
 _exported_templates
 docfx-bin
 api/*
-!api/index.md
+!api/index.md
+/index.md