Just what is this Razor thing, anyway?

The details on the page are very good, and it's great to have everything described on one page. But the article is still confusing.
Rendering, encoding, and transitioning, Oh My!

The article speaks of transitions, rendering, and encoding seemingly interchangeably, without really describing what Razor is or where it fits in the grand scheme of writing code in a file and having it appear on the screen.

Sometimes the server is rendering.
Sometimes Razor is rendering.
Sometimes Razor is encoding.

Sometimes Razor is transitioning.
Sometimes "the code" is transitioning.
Sometimes "It" is transitioning, but what "it" is is unclear.

Sometimes it's C#.
Sometimes it's HTML.
Sometimes it's Razor reserved words (introduced after it was said that a razor file holds C# and HTML (and, assumed, nothing else)
Sometimes it's Directives (which are probably related to reserved words)
Sometimes it's Razor-specific markup (which isn't really explained)

Please clearly outline what Razor is, where it fits, and what it does.
And please be consistent in the terminology and verbs.

Would you consider something like the following?

Razor is a markup language that allows you to mix C# code (or code from another .NET-based language), Razor-specific helper code, and HTML code into a single file. Razor with C# is often stored in files with a *.cshtml extension. When the page is requested, the server uses tools to read the *.cshtml file, parse it, interpret the HTML/C#/helper mix, and encode the mix into HTML-only. The server then renders the encoded HTML just like any other page. The HTML-only encoding is often longer and more tedious than the *.cshtml used to generate it.

The article speaks of 'transitioning' and rendering and is confusing. The article says:
> "Razor supports C# and uses the @ symbol to transition from HTML to C#. Razor evaluates C# expressions and renders them in the HTML output."

What do you mean by "transition"?
The article mentions that Razor is rendering. I thought the server did the rendering and Razor interprets and encodes.

The article says:
> "When an @ symbol is followed by a [Razor reserved keyword](https://learn.microsoft.com/en-us/aspnet/core/mvc/views/razor?view=aspnetcore-7.0#razor-reserved-keywords), it transitions into Razor-specific markup. Otherwise, it transitions into plain HTML."

This is the first mention that a *.cshtml file might include anything other than C# or plain HTML. Why didn't you mention that back at the beginning when you were describing what could be in those files?

What is the "it" that is transitioning?

If the @ is not followed by a Razor reserved word, it transitions to plain HTML. This is a confusing statement.
Is this trying to say that the code segment or inclusion [see below] (and not Razor itself), is encoded as plain HTML?
Or is that inclusion just added verbatim at that point in the encoding?

I think what you mean is:

An @ marks the start of a chunk of C# or Razor helper code that is being included into the HTML. There are several styles of inclusion that serve different purposes. An inclusion might be
- An Implicit Razor Expression without parentheses, e.g. `

@dateTime.Now

`
- An Explicit Razor Expression with parentheses, e.g. `

Last week this time: @(DateTime.Now - TimeSpan.FromDays(7))

`
- A Razor Code Block using braces, e.g.
` @{
var quote = "The future depends on what you do today. - Mahatma Gandhi";
}`
- A bit of C# mixed with Razor helper code, e.g.
`
@Html.DisplayNameFor(model => model.Movie[0].Title)

`
- Other Razor constructs or directives, e.g. `@page`, `@model`, `@foreach`, or `@if`

An inclusion may surround a mix of HTML and other inclusions.

The different styles of inclusion will be interpreted by the Razor tools and encoded into the final HTML page to be rendered by the server.

Each inclusion style and the other Razor constructs and directives will be described in detail in the following sections.
[end]

Having a detailed description of each directive and each inclusion style is really good, once you understand how it all fits together and get a clearer picture of which piece is doing what.

Thanks for doing this!

---
#### Document Details

⚠ *Do not edit this section. It is required for learn.microsoft.com ➟ GitHub issue linking.*

* ID: b87067b2-347c-072d-26c8-5a8c7c9c860b
* Version Independent ID: a0b3b70a-3b39-1b5f-a4ce-c41bd2d6b044
* Content: [Razor syntax reference for ASP.NET Core](https://learn.microsoft.com/en-us/aspnet/core/mvc/views/razor?view=aspnetcore-7.0#razor-syntax)
* Content Source: [aspnetcore/mvc/views/razor.md](https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/mvc/views/razor.md)
* Product: **aspnet-core**
* Technology: **aspnetcore-mvc**
* GitHub Login: @Rick-Anderson
* Microsoft Alias: **riande**