| layout | title |
|---|---|
contribute |
Contribute |
docs.scala-lang.org was intended to make it easier for the Scala team and the community at large to easily collect, organize, and "make public" many different types of documentation while making it easy for users to find, interact, and help us improve that documentation.
This website is an open-source repository of official Scala documentation, hosted on github, that is always ready for contributions.
The availability, depth, and quality of documentation is considered by many to be a huge issue.
As Scala continues to mature, it continues to attract more and more interested newcomers and potential adopters who are well accustomed to easy-to-find, abundant, quality documentation (found in other languages, like Java). For many, the learning curve becomes unnecessarily steep, and people sometimes get frustrated.
If we want Scala to be accessible to more programmers, clear, easy-to-find documentation is essential.
If you're interested in contributing to the Scala project in general, I argue that one of the most meaningful ways that you can, is to help us improve this transfer of information- let's make it easier and faster for people to get core concepts, and to answer their own questions so they can progress to Scala-proficient quickly. Each line that you contribute has the potential to affect the entire Scala community as a whole-- current, and future.
Currently, the types of documentation supported in this repository are:
- Guides/Overviews: Definitive guides/overviews of specific language features. Often long, detailed documents, often produced by members of the Scala team. An example is the excellent [Collections]({{ site.baseurl }}/overviews/collections-2.13/introduction.html) overview.
- Tutorials: Bite-size, example-rich, and concise articles meant to get a developer up to speed quickly.
- Cheatsheets: Quick reference of Scala syntax and behaviors.
This documentation repository is open-source, it lives in github repository, and is always contribution-ready.
It's statically generated from Markdown source using Jekyll, and hosted on GitHub Pages. This workflow was chosen so as to make it as easy as possible for core committers and the community alike to produce HTML documentation, and as easy as possible to publish it in a central location.
The markdown syntax being used supports Maruku extensions, and has automatic syntax highlighting, without the need for any tags.
Additionally mdoc is used during pull requests to validate Scala code blocks. To use this feature you must use the backtick notation as documented by mdoc. Note that only validation is done. The output files from mdoc are not used in the building of the tutorial. Use mdoc or mdoc:fail for your code blocks.
For one to contribute a document, one must simply fork the repo, write their article in Markdown (example below), and submit a pull request. That's it. Likely after some edits and discussion, your document will be made live on docs.scala-lang.org.
---
layout: overview
title: My Awesome Title
---
## An h2 Header in Markdown
And a paragraph, with a [link](https://www.scala-lang.org).
One can contribute code by indenting it 4 spaces, or in-line by putting backticks around it like so, `def foo`
Everything else is automatically generated for you; tables of contents, and most index pages. And of course, the styling is already taken care of for you.
The goal of this documentation repository is to be tighter and more organized than other community-driven documentation platforms, like wikis. As such, any document pulled in for inclusion on https://docs.scala-lang.org must:
- "fit in" to the repository ( i.e., it should not be a complete duplicate of another article),
- be polished it must be thorough, complete, correct, organized, and "article-like" (personal programming notes don't quite fit.)
- be maintained if the document might require revisions from time to time, it should come with an owner
If you have something you're thinking about contributing, or that you're thinking about writing in order to contribute-- we'd love to consider it! Please don't hesitate to use GitHub issues and pull requests and the scala/contributors room on Gitter for any questions, concerns, clarifications, etc.
Note: These templates will soon change slightly as a result of necessary refactoring.
A guide or an overview that can be logically placed on one page must be placed in the directory overviews/RELEVANT-CATEGORY/_posts with the file name in the format YYYY-MM-dd-title-separated-by-dashes.md, and header:
---
layout: overview
title: YOUR TITLE
---
The rest of the document should, of course, be written in Markdown.
At the moment, RELEVANT-CATEGORY corresponds to only a single category, "core," because we are currently focusing on building up documentation of core libraries. However, expect more categories here in the future.
If your document consists of multiple pages, like the [Collections]({{ site.baseurl }}/overviews/collections-2.13/introduction.html) overview, an ordering must be specified, by numbering documents in their logical order with num, and a name must be assigned to the collection of pages using partof. For example, the following header might be used for a document in the collections overview:
---
layout: overview
title: YOUR TITLE
partof: collections
num: 10
---
A single document in the collection must contain a tag in the header, outof, that indicates the total number of documents in the large overview. Putting it on the last page in the overview is often best:
---
layout: overview
title: YOUR TITLE
partof: collections
num: 15
outof: 15
---
Index pages, such as https://docs.scala-lang.org/overviews/index.html are automatically generated, assuming documents are properly placed under the correct RELEVANT-CATEGORY. So, simply drop your document into the correct folder, and you're done.
At the moment, a tutorial that can be logically placed on one page must be placed in the directory tutorials/ with the file name in the format title-separated-by-dashes.md. For the moment, single-page tutorials use the same layout as single-page overviews:
---
layout: overview
title: YOUR TITLE
---
If you have a multiple-page tutorial, like in the case of multiple-page overviews, you must both specify an ordering for your document, and a name must be assigned to the collection of tutorial pages. For example, the following header is used for the [Tour of Scala]({{ site.baseurl }}/tour/tour-of-scala.html) series of tutorial articles:
---
layout: inner-page-no-masthead
title: YOUR TITLE
tutorial: scala-tour
num: 4
---
At the moment, only indexes for multiple-page tutorials are automatically generated.
For now, cheatsheets are assumed to be in the form of tables. To contribute a cheatsheet, one must simply produce their cheatsheet as a Markdown table, with the following header:
---
layout: cheatsheet
title: YOUR TITLE
by: YOUR NAME
about: SOME TEXT ABOUT THE CHEAT SHEET.
---
The site build process uses mdoc to typecheck code snippets in markdown. This is a great way to ensure the code snippets that you're including typecheck and are valid. Here are a few quick types to get started.
To get started, you can simply add mdoc behind scala when you are creating a
code block. The mdoc modifier here will make sure that mdoc runs the code
snippet and ensures that it's valid.
```scala mdoc
val a = 1
```
If you have a snippet that you expect to fail, you can also account for this by
using mdoc:fail for a compile error mdoc:crash for a runtime-error.
```scala mdoc:fail
val b: String = 3 // won't compile
```
Keep in mind that a single file is all compiled as a single unit, so you can't
redefine a variable that was defined above in another code snippet. However
there are a couple ways to get around this. Firstly, you can use the mdoc:nest
modifier with will wrap the snippet in a scala.Predef.locally{...}. This will
essentially "hide" the snippet from the others. Another way around this is to
use the mdoc:reset modifier, which resets and forgets about everything up
above. Here is an example using the various modifiers.
```scala mdoc
import java.time.Instant
def now() = Instant.now()
object Foo {}
```
```scala mdoc:nest
case class Foo(a: Int) // conflicts with Foo above, but it's nested so it's fine
```
```scala mdoc
val a = s"The time is ${now()}" // still have access to the now method from above
```
```scala mdoc:reset
case class Foo(a: String) // forget the previous Foo's and start fresh
```
```scala mdoc
val myFoo = Foo("hi") // now we only have access to the last Foo
```