One of the major reasons for studying chemical kinetics is to use measurements of the macroscopic properties of a system, such as the rate of change in the concentration of reactants or products with time, to discover the sequence of events that occur at the molecular level during a reaction. This molecular description is the mechanism of the reaction; it describes how individual atoms, ions, or molecules interact to form particular products. The stepwise changes are collectively called the reaction mechanism.
In an internal combustion engine, for example, isooctane reacts with oxygen to give carbon dioxide and water:
2C8H18(l)+25O2(g)⟶16CO2(g)+18H2O(g)
For this reaction to occur in a single step, 25 dioxygen molecules and 2 isooctane molecules would have to collide simultaneously and be converted to 34 molecules of product, which is very unlikely. It is more likely that a complex series of reactions takes place in a stepwise fashion. Each individual reaction, which is called an elementary reaction, involves one, two, or (rarely) three atoms, molecules, or ions. The overall sequence of elementary reactions is the mechanism of the reaction. The sum of the individual steps, or elementary reactions, in the mechanism must give the balanced chemical equation for the overall reaction.
The overall sequence of elementary reactions is the mechanism of the reaction.
12-5-2: Molecularity and the Rate-Determining Step
To demonstrate how the analysis of elementary reactions helps us determine the overall reaction mechanism, we will examine the much simpler reaction of carbon monoxide with nitrogen dioxide.
2CO+2NO2→2CO2+N2O4
From the balanced chemical equation, one might expect the reaction to occur via a collision of one molecule of NO2 with a molecule of CO that results in the transfer of an oxygen atom from nitrogen to carbon. The experimentally determined rate law for the reaction, however, is as follows:
rate =k[NO2]2
The fact that the reaction is second order in [NO2] and independent of [CO] tells us that it does not occur by the simple collision model outlined previously. If it did, its predicted rate law would be
rate =k[NO2][CO].
The following two-step mechanism is consistent with the rate law if step 1 is much slower than step 2:
According to this mechanism, the overall reaction occurs in two steps, or elementary reactions. Summing steps 1 and 2 and canceling on both sides of the equation gives the overall balanced chemical equation for the reaction. The NO3 molecule is intermediate in the reaction, a species that does not appear in the balanced chemical equation for the overall reaction. It is formed as a product of the first step but is consumed in the second step.
The sum of the elementary reactions in a reaction mechanism must give the overall balanced chemical equation of the reaction.
12-5-3: Using Molecularity to Describe a Rate Law
The molecularity of an elementary reaction is the number of molecules that collide during that step in the mechanism. If there is only a single reactant molecule in an elementary reaction, that step is designated as unimolecular; if there are two reactant molecules, it is bimolecular; and if there are three reactant molecules (a relatively rare situation), it is termolecular. Elementary reactions that involve the simultaneous collision of more than three molecules are highly improbable and have never been observed experimentally. (To understand why, try to make three or more marbles or pool balls collide with one another simultaneously!)
About the image
The Basis for Writing Rate Laws of Elementary Reactions. This diagram illustrates how the number of possible collisions per unit time between two reactant species, A and B, depends on the number of A and B particles present. The number of collisions between A and B particles increases as the product of the number of particles, not as the sum. This is why the rate law for an elementary reaction depends on the product of the concentrations of the species that collide in that step. (CC BY-NC-SA; anonymous)
Writing the rate law for an elementary reaction is straightforward because we know how many molecules must collide simultaneously for the elementary reaction to occur; hence the order of the elementary reaction is the same as its molecularity (Table 14.6.1). In contrast, the rate law for the reaction cannot be determined from the balanced chemical equation for the overall reaction. The general rate law for a unimolecular elementary reaction ( A→ products) is
rate =k[A].
For bimolecular reactions, the reaction rate depends on the number of collisions per unit time, which is proportional to the product of the concentrations of the reactants, as shown in Figure 14.6.1 For a bimolecular elementary reaction of the form A+B→ products, the general rate law is
rate =k[A][B].
Elementary Reaction
Molecularity
Rate
Reaction Order
A→ products
Unimolecular
rate =k[A]
first
2A→ products
Bimolecular
rate =k[A]2
second
A+B→ products
Bimolecular
rate =k[A][B]
second
2A+B→ products
Termolecular
rate =k[A]2[B]
third
A+B+C→ products
Termolecular
rate =k[A][B][C]
third
For elementary reactions, the order of the elementary reaction is the same as its molecularity. In contrast, the rate law cannot be determined from the balanced chemical equation for the overall reaction (unless it is a single step mechanism and is therefore also an elementary step).
Note the important difference between writing rate laws for elementary reactions and the balanced chemical equation of the overall reaction. Because the balanced chemical equation does not necessarily reveal the individual elementary reactions by which the reaction occurs, we cannot obtain the rate law for a reaction from the overall balanced chemical equation alone. In fact, it is the rate law for the slowest overall reaction, which is the same as the rate law for the slowest step in the reaction mechanism, the ratedetermining step, that must give the experimentally determined rate law for the overall reaction.This statement is true if one step is substantially slower than all the others, typically by a factor of 10 or more. If two or more slow steps have comparable rates, the experimentally determined rate laws can become complex. Our discussion is limited to reactions in which one step can be identified as being substantially slower than any other. The reason for this is that any process that occurs through a sequence of steps can take place no faster than the slowest step in the sequence. In an automotive assembly line, for example, a component cannot be used faster than it is produced. Similarly, blood pressure is regulated by the flow of blood through the smallest passages, the capillaries. Because movement through capillaries constitutes the rate-determining step in blood flow, blood pressure can be regulated by medications that cause the capillaries to contract or dilate. A chemical reaction that occurs via a series of elementary reactions can take place no faster than the slowest step in the series of reactions.
Look at the rate laws for each elementary reaction in the example as well as for the overall reaction.
Rate laws for each elementary reaction in our example as well as for the overall reaction
Steps
Reaction
Rate
step 1
NO2+NO2→k1NO3+NO
rate =k1[NO2]2( predicted)
step 2
NO3+CO→k2NO2+CO2
rate =k2[NO3][CO]( predicted )
step 3
NO2+CO→kNO+CO2
rate =k[NO2]2( observed)
The experimentally determined rate law for the reaction of NO2 with CO is the same as the predicted rate law for step 1 . This tells us that the first elementary reaction is the rate-determining step, so k for the overall reaction must equal k1. That is, NO3 is formed slowly in step 1, but once it is formed, it reacts very rapidly with CO in step 2.
Sometimes chemists are able to propose two or more mechanisms that are consistent with the available data. If a proposed mechanism predicts the wrong experimental rate law, however, the mechanism must be incorrect.
12-5-4-1: Example-A Reaction with an Intermediate
In an alternative mechanism for the reaction of NO2 with CO with N2O4 appearing as an intermediate.
alternative mechanism for the reaction of NO2 with CO with N2O4 appearing as an intermediate.
Write the rate law for each elementary reaction. Is this mechanism consistent with the experimentally determined rate law (rate =k[NO2]2t)
Given: elementary reactions Asked for: rate law for each elementary reaction and overall rate law
Determine the rate law for each elementary reaction in the reaction.
Determine which rate law corresponds to the experimentally determined rate law for the reaction. This rate law is the one for the rate-determining step.
A The rate law for step 1 is rate =k1[NO2]2; for step 2 , it is rate =k2[N2O4][CO].
B If step 1 is slow (and therefore the rate-determining step), then the overall rate law for the reaction will be the same: rate =k1[NO2]2. This is the same as the experimentally determined rate law. Hence this mechanism, with N2O4 as an intermediate, and the one described previously, with NO3 as an intermediate, are kinetically indistinguishable. In this case, further experiments are needed to distinguish between them. For example, the researcher could try to detect the proposed intermediates, NO3 and N2O4, directly.
At 500K in the presence of a copper surface, ethanol decomposes according to the equation
C2H5OH(g)⟶CH3CHO(g)+H2(g)
The pressure of C2H5OH was measured as a function of time and the following data were obtained:
Time (s)
PC2H5OH (torr)
0
250.
100.
237
200.
224
300.
211
400.
198
500.
185
Since the pressure of a gas is directly proportional to the concentration of gas, we can express the rate law for a gaseous reaction in terms of partial pressures. Using the above data, deduce the rate law, the integrated rate law, and the value of the rate constant, all in terms of pressure units in atm and time in seconds. Predict the pressure of C2H5OH after 900.s from the start of the reaction. (Hint: To determine the order of the reaction with respect to C2H5OH, compare how the pressure of C2H5OH decreases with each time listing.)
The decomposition of N2O5(g) is represented by the equation above. A sample of N2O5(g) is monitored as it decomposes, and the concentration of N2O5 as a function of time is recorded. The results are shown in the table below.
Time (s)
[N2O5]
0
1.000
25.0
0.801
50.0
0.642
75.0
0.515
Calculate the average rate of the reaction between 50.0 and 75.0 seconds.
Notice that the rate of change in concentration of each species is divided by its coefficient from the balanced chemical equation ( a, b,c, or d ). This ensures that the calculated reaction rate is the same no matter which reactant or product is monitored for changes in concentration. In this case, the monitored species was N2O5. With that in mind, let's write the reaction rate in terms of the rate of change in concentration of N2O5 :
rate =−21ΔtΔ[N2O5]
Since the coefficient for N2O5 in the balanced equation is 2 , we divided the rate of change in concentration of N2O5 by 2 . Additionally, since N2O5 is being consumed in the reaction, we included a negative sign in front of the expression.
Now, let's plug in the information from the table to calculate the average reaction rate between 50.0 and 75.0 seconds:
The rate law for a particular reaction is rate =k[XY]2. In an experiment, the initial rate of the reaction is determined to be 0.16mol/(L⋅s) when the initial concentration of XY is 0.40mol/L.
What is the value of the rate constant, k, for the reaction?
To solve this problem, let's first write out the rate law for the reaction. According to the text, the reaction is second order with respect to X and first order with respect to Y, so the rate law is rate =k[X]2[Y]
Now, let's think about how the rate changes when [X] is halved and [Y] is doubled. Since [X] is raised to the second power in the rate law, halving [X] decreases the reaction rate by a factor of 4 . Similarly, since [Y] is raised to the first power, doubling [Y] increases the reaction rate by a factor of 2 . Combined, these changes result in the reaction rate decreasing by a factor of 2 overall. So, when [X] is halved and [Y] is doubled, the rate of the reaction decreases by a factor of 2 .
Patterns of Organization and Methods of Development
Patterns of organization can help your readers follow the ideas within your essay and your paragraphs, but they can also work as methods of development to help you recognize and further develop ideas and relationships in your writing. Here are some strategies that can help you with both organization and development in your essays.
Now take the pie out of the oven and let it cool on the stovetop.
Mix the dry ingredients with the liquid ingredients.
Set the pie crust aside while you make the filling.
How did it feel to read the above list? A bit confusing, I would guess. That’s because the steps for making a pie were not well organized, and the steps don’t include enough detail for us to know exactly what we should do. (Like what are the dry and liquid ingredients?) We all know that starting instructions from the beginning and giving each detailed step in the order it should happen is vital to having a good outcome, in this case a yummy pie! But it’s not always so simple to know how to organize or develop ideas, and sometimes there’s more than one way, which complicates things even further.
First, let’s take a look at a couple of ways to think about organization.
It might be useful to think about organizing your topic like a triangle:
The first triangle represents starting with the most general, big picture information first, moving then to more detailed and often more personal information later in the paper. The second triangle represents an organizational structure that starts with the specific, small scale information first and then moves to the more global, big picture stuff.
For example, if your topic is traffic in Vancouver, British Columbia, an essay that uses the general-to-specific organizational structure might begin this way:
Many people consider Vancouver, British Columbia, to be a relaxed place to live. They would be shocked to know how bad the traffic is traveling major arteries into the city and even driving around the city itself.
An essay that uses the specific-to-general structure might start like this:
Transit is crowded, parking is expensive, and vehicles stop and go through the main streets of the city of Vancouver, British Columbia, and that is just once travelers brave the crowded arteries to enter the city; Vancouver’s traffic problem does not lend itself to the relaxed atmosphere many believe the city to have.
What’s the difference between these two introductions? And how might they appeal to the intended audience for this essay in different ways? The first introduction is looking at the big picture of the problem and mentions pollution’s impact on all citizens in Portland, while the second introduction focuses on one specific family. The first helps readers see how vast the problem really is, and the second helps connect readers to a real family, making an emotional appeal from the very beginning. Neither introduction is necessarily better. You’ll choose one over the other based on the kind of tone you’d like to create and how you’d like to affect your audience. It’s completely up to you to make this decision.
Does the Triangle Mean the Essay Keeps Getting More Specific or More Broad until the Very End?
The triangle is kind of a general guide, meaning you’re allowed to move around within it all you want. For example, it’s possible that each of your paragraphs will be its own triangle, starting with the general or specific and moving out or in. However, if you begin very broadly, it might be effective to end your essay in a more specific, personal way. And if you begin with a personal story, consider ending your essay by touching on the global impact and importance of your topic.
Are There Other Ways to Think about Organizing My Ideas?
Yes! Rather than thinking about which of your ideas are most specific or personal or which are more broad or universal, you might consider one of the following ways of organizing your ideas:
Most important information first (consider what you want readers to focus on first)
Chronological order (the order in time that events take place)
Compare and contrast (ideas are organized together because of their relationship to each other)
The section on Methods of Development, below, offers more detail about some of these organizational patterns, along with some others.
Choose one of the following topics, and practice writing a few opening sentences like we did above, once using the general-to-specific format and once using the specific-to-general. Which do you like better? What audience would be attracted to which one? Share with peers to see how others tackled this challenge. How would you rewrite their sentences? Why? Discuss your changes and listen to how your peers have revised your sentences. Taking in other people’s ideas will help you see new ways to approach your own writing and thinking. Topics:
The methods of development covered here are best used as ways to look at what’s already happening in your draft and to consider how you might emphasize or expand on any existing patterns. You might already be familiar with some of these patterns because teachers will sometimes assign them as the purpose for writing an essay. For example, you might have been asked to write a cause-and-effect essay or a comparison-and-contrast essay.
It’s important to emphasize here that patterns of organization or methods of developing content usually happen naturally as a consequence of the way the writer engages with and organizes information while writing. That is to say, most writers don’t sit down and say, “I think I’ll write a cause-and-effect essay today.” Instead, a writer might be more likely to be interested in a topic, say, the state of drinking water in the local community, and as the writer begins to explore the topic, certain cause-and-effect relationships between environmental pollutants and the community water supply may begin to emerge.
So if these patterns just occur naturally in writing, what’s the use in knowing about them? Well, sometimes you might be revising a draft and notice that some of your paragraphs are a bit underdeveloped. Maybe they lack a clear topic, or maybe they lack support. In either case, you can look to these common methods of development to find ways to sharpen those vague topics or to add support where needed. Do you have a clear cause statement somewhere but you haven’t explored the effects? Are you lacking detail somewhere where a narrative story or historical chronology can help build reader interest and add support? Are you struggling to define an idea that might benefit from some comparison or contrast? Read on to consider some of the ways that these strategies can help you in revision.
Do you see a potential cause-and-effect relationship developing in your draft? The cause-and-effect pattern may be used to identify one or more causes followed by one or more effects or results. Or you may reverse this sequence and describe effects first and then the cause or causes. For example, the causes of water pollution might be followed by its effects on both humans and animals. You may use obvious transitions to clarify cause and effect, such as “What are the results? Here are some of them…” or you might simply use the words cause, effect, and result, to cue the reader about your about the relationships that you’re establishing.
At some point does your essay explore a problem or suggest a solution? The problem-solution pattern is commonly used in identifying something that’s wrong and in contemplating what might be done to remedy the situation. There are probably more ways to organize a problem-solution approach, but but here are three possibilities:
Describe the problem, followed by the solution.
Propose the solution first and then describe the problems that motivated it.
Or a problem may be followed by several solutions, one of which is selected as the best.
When the solution is stated at the end of the paper, the pattern is sometimes called the delayed proposal. For a hostile audience, it may be effective to describe the problem, show why other solutions do not work, and finally suggest the favored solution. You can emphasize the words problem and solution to signal these sections of your paper for your reader.
Do you need to develop support for a topic where telling a story can illustrate some important concept for your readers? Material arranged chronologically is explained as it occurs in time. A chronological or narrative method of development might help you find a way to add both interest and content to your essay. Material arranged chronologically is explained as it occurs in time. This pattern may be used to establish what has happened. Chronology or narrative can be a great way to introduce your essay by providing a background or history behind your topic. Or you may want to tell a story to develop one or more points in the body of your essay. You can use transitional words like then, next, and finally to make the parts of the chronology clear.
Are you trying to define something? Do you need your readers to understand what something is and what it is not? The comparison-and-contrast method of development is particularly useful in extending a definition, or anywhere you need to show how a subject is like or unlike another subject. For example, the statement is often made that drug abuse is a medical problem instead of a criminal justice issue. An author might attempt to prove this point by comparing drug addiction to AIDS, cancer, or heart disease to redefine the term “addiction” as a medical problem. A statement in opposition to this idea could just as easily establish contrast by explaining all the ways that addiction is different from what we traditionally understand as an illness. In seeking to establish comparison or contrast in your writing, some words or terms that might be useful are by contrast, in comparison, while, some, and others.
Summary
These four methods of development—cause and effect, problem-solution, chronology or narrative, and comparison and contrast—are just a few ways to organize and develop ideas and content in your essays. It’s important to note that they should not be a starting point for writers who want to write something authentic—something that they care deeply about. Instead, they can be a great way to help you look for what’s already happening with your topic or in a draft, to help you to write more, or to help you reorganize some parts of an essay that seem to lack connection or feel disjointed. Look for organizational patterns when you’re reading work by professional writers. Notice where they combine strategies (e.g., a problem-solution pattern that uses cause-and-effect organization, or a comparison-contrast pattern that uses narrative or chronology to develop similarities or differences). Pay attention to how different writers emphasize and develop their main ideas, and use what you find to inspire you in your own writing. Better yet, work on developing completely new patterns of your own.
Reference
This chapter was adapted from “Patterns of Organization and Methods of Development” in The Word on College Reading and Writing by Carol Burnell, Jaime Wood, Monique Babin, Susan Pesznecker, and Nicole Rosevear, which is licensed under a CC BY-NC 4.0 Licence. Adapted by Allison Kilgannon.
“General to Specific vs. Specific to General Triangles” by Carol Burnell, Jaime Wood, Monique Babin, Susan Pesznecker, and Nicole Rosevear is under a CC BY-NC 4.0 Licence.
Kilgannon, Allison. “Patterns of Organization and Methods of Development.” Opentextbc.ca, 20 Aug. 2021, opentextbc.ca/advancedenglish/chapter/patterns-of-organization-and-methods-of-development/#:~:text=These%20four%20methods%20of%20development.
This table of vocabularies are from "Sadlier Vocabulary Workshop-Level G (Unit 4)" with their corresponding textbook definitions and part of speeches (from some of them) made into a collection.
Vocabulary
Definition
Atrophy
(n.) the wasting away of a body organ or tissue; any progressive decline or failure; (v.) to waste away
Bastion
A fortified place, stronghold
Concord
A state of agreement, harmony, unanimity; a treaty, pact, covenant
Consummate
(adj.) complete or perfect in the highest degree; (v.) to bring to a state of completion or perfection
Disarray
(n.) disorder, confusion; (v.) to throw into disorder
Exigency
Urgency, pressure; urgent demand, pressing need; an emergency
Flotsam
Floating debris; homeless, impoverished people
Frenetic
Frenzied, highly agitated
Glean
To gather bit by bit; to gather small quantities of grain left in a field by the reapers.
Grouse
(n.) A type of game bird; a complaint; (v.) to complain, grumble
Incarcerate
To imprison, confine, jail
Incumbent
(adj.) obligatory, required; (n.) one who holds a specific office at the time spoken of
Jocular
Humorous, jesting, jolly, joking
Ludicrous
Ridiculous, laughable, absurd
Mordant
Biting or caustic in thought, manner, or style; sharply or bitterly harsh.
Nettle
(n.) a prickly or stinging plant; (v.) to arouse displeasure, impatience, or anger; to vex or irritate severely
Pecuniary
Consisting of or measured in money; of or related to money
Pusillanimous
Contemptibly cowardly or mean-spirited
Recumbent
In a reclining position, lying down, in the posture of one sleeping or resting.
Stratagem
A scheme to outwit or deceive an opponent or to gain and end.
Before you start using this plugin, make sure you have already installed the default markdown-it parser; if not, please run the following command or refer to the official markdown-it documentation.
sh
$npminstallmarkdown-it--save
$npminstallmarkdown-it--save
1
First install package with your preferred package manager (npm, yarn, pnpm), or include javascript before the closing </body> for markdown-it-katex's core utils to be loaded for the static page.
Before you start using this plugin, make sure you have already installed the default markdown-it parser; if not, please run the following command or refer to the official markdown-it documentation.
sh
$npminstallmarkdown-it--save
$npminstallmarkdown-it--save
1
First install package with your preferred package manager (npm, yarn, pnpm), or include javascript before the closing </body> for markdown-it-katex's core utils to be loaded for the static page.
sh
$npminstall-D@andatoshiki/markdown-it-katex
$npminstall-D@andatoshiki/markdown-it-katex
1
sh
$yarnadd--dev@andatoshiki/markdown-it-katex
$yarnadd--dev@andatoshiki/markdown-it-katex
1
sh
$pnpmadd-D@andatoshiki/markdown-it-katex
$pnpmadd-D@andatoshiki/markdown-it-katex
1
html
<!-- your other body contents ... --><scriptsrc="https://unpkg.com/@andatoshiki/markdown-it-katex@0.0.3/markdown-it-katex.min.js"></script></body>
<!-- your other body contents ... --><scriptsrc="https://unpkg.com/@andatoshiki/markdown-it-katex@0.0.3/markdown-it-katex.min.js"></script>
-</body>
1 2 3
Including KaTeX CSS is necessary in the way you are convenient with, either link the stylesheet from a third party CDN into the local HTML <head> tag or import it into a currently linked CSS stylesheets to enable styles for KaTeX globally as follows,
Or, you could clone or download the entire repository source of KaTeX and self load the fonts/styles/scripts locally, but if you prefer loading from third-party CDN with faster load speed when deployed to save your server resources, the following CDN links might be your choice, you can always switch to other platforms based on your need.
Including KaTeX CSS is necessary in the way you are convenient with, either link the stylesheet from a third party CDN into the local HTML <head> tag or import it into a currently linked CSS stylesheets to enable styles for KaTeX globally as follows,
Or, you could clone or download the entire repository source of KaTeX and self load the fonts/styles/scripts locally, but if you prefer loading from third-party CDN with faster load speed when deployed to save your server resources, the following CDN links might be your choice, you can always switch to other platforms based on your need.
// ... your other styles@import'https://cdnjs.toshiki.dev/ajax/libs/KaTeX/0.16.0/katex.min.css';
// ... your other styles
-@import'https://cdnjs.toshiki.dev/ajax/libs/KaTeX/0.16.0/katex.min.css';
1 2
If you are using the default markdown-it parser, I personally recommend that you use the GitHub markdown CSS (github-markdown-css) for styling your HTML output with a similar style replica of GitHub's markdown styling to your familiarity.
This forked project maintained by Anda Toshiki comes with the update of KaTeX components with higher style version support (this documentation uses KaTeX version 16.0, without hassels), later versions may works, but no guarantees are given by the developers, if you are not obsessed with the latest released version, 16.0 may fits your need for loading KaTeX on a personal blog site or small educational sites; yet it should work fully functionally.
Warning
Since this project is a fork of the original markdown-it-katex project that hasn't been receiving any active updates of its code source for years, the latest katex style version supported is somewhere around ver. 0.9.0 which clearly is outdated and results in broken styles with overflowing and other potential bug presents.
If you are using the default markdown-it parser, I personally recommend that you use the GitHub markdown CSS (github-markdown-css) for styling your HTML output with a similar style replica of GitHub's markdown styling to your familiarity.
This forked project maintained by Anda Toshiki comes with the update of KaTeX components with higher style version support (this documentation uses KaTeX version 16.0, without hassels), later versions may works, but no guarantees are given by the developers, if you are not obsessed with the latest released version, 16.0 may fits your need for loading KaTeX on a personal blog site or small educational sites; yet it should work fully functionally.
Warning
Since this project is a fork of the original markdown-it-katex project that hasn't been receiving any active updates of its code source for years, the latest katex style version supported is somewhere around ver. 0.9.0 which clearly is outdated and results in broken styles with overflowing and other potential bug presents.
Math parsing in markdown is designed to comply with the "latex-in-markdown" conventions set by Pandoc,
Anything between two $ characters will be treated as TeX math. The opening $ must have a non-space character immediately to its right, while the closing $ must have a non-space character immediately to its left, and must not be followed immediately by a digit. Thus, $20,000 and $30,000 won’t parse as math. If for some reason you need to enclose text in literal $ characters, backslash-escape them and they won’t be treated as math delimiters.
KaTeX is a popular, open-source math typesetting library that is based on TeX and LaTeX. It is designed to be easy to use, and to provide high-quality mathematical typesetting for web applications, refer to the following pages of the document for the full list of function support in KaTeX.
Note
Due to the large number of equations rendered on the next following pages, it might takes time to entirely load the webpage, please be patient if the webpage seems to not respond; or it could be a result of slow network connection to correctly render all the equation that causes broken formulas, refresh the page to proceed.
KaTeX works out of the box on large screen devices such as laptops and desktop computers. But as KaTeX's built-in does not support responsiveness on it's default stylings, hence KaTeX equations might overflow out of the default width of the default application containers on small-screened mobile devices as you can see in the following image in the dev tool of chrome, when the dimension of the webpage is set to responsive or under a certain fixed device dimension, the equations rendered in KaTeX overflows out of the viewport as inspected in blue hightlight.
◎ katex overflowing on small screen devices
This inevitably causes the viewport to break and extends the default width for KaTeX equations <div> to fit, users will be required to manually scroll right in order to view the full equation consequently as follows,
◎ katex overflowing with labels annotated
The above situation is undoubtedly annoying for user experiences while reading documentation, consider at what scenarios users have to scroll, scroll and scroll only for viewing a single long-blocked equation, who would want to read such a text, right? But don't worry we have a simple fix for this situation via by several line of css.
If you happened to search over KaTeX's official repo issue tracker on GitHub, there are several user-made css tweaks hack already, the fix is simple by adjusting the overflows of both x and y axes of the KaTeX render <div> blocks. The katex-display > .katex selector targets the child element of the .katex-display class that has the .katex class. This is the element that contains the KaTeX math expression. The first block of styles is mostly concerned with making sure that the KaTeX expression doesn't overflow its container and can be scrolled horizontally if needed. The second block of styles sets the font and line-height for the KaTeX expression and makes sure that its text is properly indented.
But, the issue here is, the overflowing issue is resolved on the webpage, but the style itself left with a slight whitish "box" at the crossing corner of both horizontal as well as vertical scrollbar tracks, this might not be so explicit in the light mode of the webpage, but when it turns to dark mode, the box become annoying. Some people might say it's an easy tweak via setting the display property of the "box" element to display: none; to directly remove the box out of the page, this is a smart approach; however, while the box is gone, the two crossing tracks is going to form an untouched invisible box again against two bars without color. Thus, neither ways seems to perfectly solve the problem.
After running a quick research on Google, I found a simple hack tweak used in a theme of VuePress, vuepress-theme-hope on GitHub, the theme both integrate with KaTeX and MathJax for math supports.
Under the styles directory of the repository, several line of scss styles came across my eyes,
◎ KaTeX tweak fix styles in theme
this scss lines only add a horizontal trackbar at the bottom of each overflowing equation while maximizing the vertical height of the equation, when user is on a small screened device as follows,
◎ Horizontal scrollbar of equations on small screen
If you are running a documentation site like this version controlled via Node, especially VitePress without native scss supports, your fix would be installing scss support globally across the project, then add the scss styles and finally import the stylesheets to take effect globally.
Install global scss support using your favored package manager.
sh
$npminstall-Dscss
$npminstall-Dscss
1
sh
$yarnadd--devscss
$yarnadd--devscss
1
sh
$pnpmadd-Dscss
$pnpmadd-Dscss
1
Then in your scss stylesheets, add the following and link or import them to your global styles, you should be off to go with a complete fix-up for KaTeX.
KaTeX works out of the box on large screen devices such as laptops and desktop computers. But as KaTeX's built-in does not support responsiveness on it's default stylings, hence KaTeX equations might overflow out of the default width of the default application containers on small-screened mobile devices as you can see in the following image in the dev tool of chrome, when the dimension of the webpage is set to responsive or under a certain fixed device dimension, the equations rendered in KaTeX overflows out of the viewport as inspected in blue hightlight.
◎ katex overflowing on small screen devices
This inevitably causes the viewport to break and extends the default width for KaTeX equations <div> to fit, users will be required to manually scroll right in order to view the full equation consequently as follows,
◎ katex overflowing with labels annotated
The above situation is undoubtedly annoying for user experiences while reading documentation, consider at what scenarios users have to scroll, scroll and scroll only for viewing a single long-blocked equation, who would want to read such a text, right? But don't worry we have a simple fix for this situation via by several line of css.
If you happened to search over KaTeX's official repo issue tracker on GitHub, there are several user-made css tweaks hack already, the fix is simple by adjusting the overflows of both x and y axes of the KaTeX render <div> blocks. The katex-display > .katex selector targets the child element of the .katex-display class that has the .katex class. This is the element that contains the KaTeX math expression. The first block of styles is mostly concerned with making sure that the KaTeX expression doesn't overflow its container and can be scrolled horizontally if needed. The second block of styles sets the font and line-height for the KaTeX expression and makes sure that its text is properly indented.
But, the issue here is, the overflowing issue is resolved on the webpage, but the style itself left with a slight whitish "box" at the crossing corner of both horizontal as well as vertical scrollbar tracks, this might not be so explicit in the light mode of the webpage, but when it turns to dark mode, the box become annoying. Some people might say it's an easy tweak via setting the display property of the "box" element to display: none; to directly remove the box out of the page, this is a smart approach; however, while the box is gone, the two crossing tracks is going to form an untouched invisible box again against two bars without color. Thus, neither ways seems to perfectly solve the problem.
After running a quick research on Google, I found a simple hack tweak used in a theme of VuePress, vuepress-theme-hope on GitHub, the theme both integrate with KaTeX and MathJax for math supports.
Under the styles directory of the repository, several line of scss styles came across my eyes,
◎ KaTeX tweak fix styles in theme
this scss lines only add a horizontal trackbar at the bottom of each overflowing equation while maximizing the vertical height of the equation, when user is on a small screened device as follows,
◎ Horizontal scrollbar of equations on small screen
If you are running a documentation site like this version controlled via Node, especially VitePress without native scss supports, your fix would be installing scss support globally across the project, then add the scss styles and finally import the stylesheets to take effect globally.
Install global scss support using your favored package manager.
sh
$npminstall-Dscss
$npminstall-Dscss
1
sh
$yarnadd--devscss
$yarnadd--devscss
1
sh
$pnpmadd-Dscss
$pnpmadd-Dscss
1
Then in your scss stylesheets, add the following and link or import them to your global styles, you should be off to go with a complete fix-up for KaTeX.
Annotate has a lot more controls than most of the other Twoslash commands, because each use of it probably needs to feel a bit different. Here's an example based on the TypeScript home page, click it to get it running so we can talk about what it does:
ts
ts
functioncompact(arr) {
if (.length>10) returnarr.trim(0, 10)
Cannot find name 'orr'.2304Cannot find name 'orr'.
Annotate has a lot more controls than most of the other Twoslash commands, because each use of it probably needs to feel a bit different. Here's an example based on the TypeScript home page, click it to get it running so we can talk about what it does:
ts
ts
functioncompact(arr) {
if (.length>10) returnarr.trim(0, 10)
Cannot find name 'orr'.2304Cannot find name 'orr'.
returnarr
}
First up, cool — it adds some text to the left hand side of the code. It features quite a few different options, so lets go through them one by one:
left or right: It's currently left. It's worth noting the arrow flips also, and 90deg isn't a great option. Let's look at that next.
{ "arrrowRot": "90deg 8px 27px" } - This JSON object is used to manipulate the annotation, you have 3 controls for arrow positioning and rotation: degrees x y. I recommend keeping those in degrees and px, but it's your life. These are overrides from defaults which are okay, but not really something you ever want to ship.
{ "textDegree": "3deg" } - Rotates the text, you probably want something between -3deg and 3deg. Optional, defaults to 0.
{ "top": "0rem" } - Sets the y coordinates for the annotation relative to the code sample, if it's not included then it becomes [lineNum]rem.
What's not included in this sample is flipped, which can be used to flip the arrow's orientation. Here's some examples:
A horizontal right example:
ts
ts
functioncompact(arr) {
if (.length>10) returnarr.trim(0, 10)
Cannot find name 'orr'.2304Cannot find name 'orr'.
returnarr
}
+```
1 2 3 4 5 6 7 8 9 10
First up, cool — it adds some text to the left hand side of the code. It features quite a few different options, so lets go through them one by one:
left or right: It's currently left. It's worth noting the arrow flips also, and 90deg isn't a great option. Let's look at that next.
{ "arrrowRot": "90deg 8px 27px" } - This JSON object is used to manipulate the annotation, you have 3 controls for arrow positioning and rotation: degrees x y. I recommend keeping those in degrees and px, but it's your life. These are overrides from defaults which are okay, but not really something you ever want to ship.
{ "textDegree": "3deg" } - Rotates the text, you probably want something between -3deg and 3deg. Optional, defaults to 0.
{ "top": "0rem" } - Sets the y coordinates for the annotation relative to the code sample, if it's not included then it becomes [lineNum]rem.
What's not included in this sample is flipped, which can be used to flip the arrow's orientation. Here's some examples:
A horizontal right example:
ts
ts
functioncompact(arr) {
if (.length>10) returnarr.trim(0, 10)
Cannot find name 'orr'.2304Cannot find name 'orr'.
returnarr
}
Upside down arrow pointing at the error, using flipped to re-flip the arrow:
ts
ts
functioncompact(arr) {
if (.length>10) returnarr.trim(0, 10)
Cannot find name 'orr'.2304Cannot find name 'orr'.
returnarr
}
+```
1 2 3 4 5 6 7 8 9 10
Upside down arrow pointing at the error, using flipped to re-flip the arrow:
ts
ts
functioncompact(arr) {
if (.length>10) returnarr.trim(0, 10)
Cannot find name 'orr'.2304Cannot find name 'orr'.
Every Twoslash code example needs to be a complete TypeScript program so it can compile. Quite often to make it compile, there is a bunch of code which isn't relevant to the user. This can be extracted out of the code examples via cut comments.
Cut works after TypeScript has generated the project and pulled out all the editor information (like identifiers, queries, highlights etc) and then amends all of their offsets and lines to re-fit the smaller output. What your user sees is everything below the ---cut---.
Every Twoslash code example needs to be a complete TypeScript program so it can compile. Quite often to make it compile, there is a bunch of code which isn't relevant to the user. This can be extracted out of the code examples via cut comments.
Cut works after TypeScript has generated the project and pulled out all the editor information (like identifiers, queries, highlights etc) and then amends all of their offsets and lines to re-fit the smaller output. What your user sees is everything below the ---cut---.
Cutting even works across multiple files. This is why // @filename: [file] is specifically the only Twoslash command which is not removed, because if it's not relevant it can be ---cut--- away.
ts
ts
import { ```
1 2 3 4 5
Cutting even works across multiple files. This is why // @filename: [file] is specifically the only Twoslash command which is not removed, because if it's not relevant it can be ---cut--- away.
Running a Twoslash code example is a full TypeScript compiler run that will create files inside the virtual file system. You can replace the contents of your code examples with the results of running TypeScript over the project.
Running a Twoslash code example is a full TypeScript compiler run that will create files inside the virtual file system. You can replace the contents of your code examples with the results of running TypeScript over the project.
While the .js file is probably the most useful file out of the box, TypeScript does emit other files if you have the right flags enabled (.d.ts and .map) but also when you have a multi-file code sample — you might need to tell Twoslash which file to show. For all these cases you can also add @showEmittedFile: [file] to tell Twoslash which file you want to show.
Shows emitted .d.ts for a TypeScript code example:
While the .js file is probably the most useful file out of the box, TypeScript does emit other files if you have the right flags enabled (.d.ts and .map) but also when you have a multi-file code sample — you might need to tell Twoslash which file to show. For all these cases you can also add @showEmittedFile: [file] to tell Twoslash which file you want to show.
Shows emitted .d.ts for a TypeScript code example:
Most of the time, you want to avoid errors in your code examples. Strictly speaking, this usually means setting the right compiler flags and environment in each code example.
Sometimes however, you do want to raise a compiler error — to show incorrect states. In those cases, twoslash has a way to mark the compiler errors you expect.
All TypeScript compiler errors have a number, this number is relatively arbitrary and can change between TypeScript versions. For our case these numbers are useul in declaring what we expect to see.
You can use // @errors: [num] to tell Twoslash that you expect this error to occur. This moves the compiler error message into the code example.
ts
ts
consta='123'
=132
Cannot assign to 'a' because it is a constant.2588Cannot assign to 'a' because it is a constant.
ts
consta='123'
=132
Cannot assign to 'a' because it is a constant.2588Cannot assign to 'a' because it is a constant.
Most of the time, you want to avoid errors in your code examples. Strictly speaking, this usually means setting the right compiler flags and environment in each code example.
Sometimes however, you do want to raise a compiler error — to show incorrect states. In those cases, twoslash has a way to mark the compiler errors you expect.
All TypeScript compiler errors have a number, this number is relatively arbitrary and can change between TypeScript versions. For our case these numbers are useul in declaring what we expect to see.
You can use // @errors: [num] to tell Twoslash that you expect this error to occur. This moves the compiler error message into the code example.
ts
ts
consta='123'
=132
Cannot assign to 'a' because it is a constant.2588Cannot assign to 'a' because it is a constant.
ts
consta='123'
=132
Cannot assign to 'a' because it is a constant.2588Cannot assign to 'a' because it is a constant.
Sometimes you have needs in which a broken TypeScript build is okay. A good example of this is using a completion query, which requires a broken TypeScript project to work. You can use // @noErrors to supress all errors in a code sample, and not have them show inline.
Sometimes you have needs in which a broken TypeScript build is okay. A good example of this is using a completion query, which requires a broken TypeScript project to work. You can use // @noErrors to supress all errors in a code sample, and not have them show inline.