Programming language: Swift
Tags: Command Line    
Latest version: v0.6.0

nef alternatives and similar libraries

Based on the "Command Line" category

Do you think we are missing an alternative of nef or a related project?

Add another 'Command Line' Library



nef, short for Nefertiti, mother of Ankhesenamun, is a toolset to ease the creation of documentation in the form of Xcode Playgrounds. It provides compile-time verification of documentation, exports it in Markdown format that can be consumed by Jekyll to generate websites, and export Carbon snippets for a given Xcode Playground.

nef is inspired by ΛNK for Kotlin and tut for Scala.


💡 Eases the creation of Xcode Playgrounds with support for [third party libraries](#-creating-a-xcode-playground).

💡 [Compiles Xcode Playgrounds](#-compiling-a-xcode-playground) with support for 3rd-party libraries from the command line.

💡 Builds a [Playground Book](#-creating-a-playground-book) for iPad with external dependencies defined in a Swift Package.

💡 Generates [Markdown](#-generating-a-markdown-project) project from Xcode Playground.

💡 Generates Markdown files that can be consumed from [Jekyll](#-generating-markdown-files-for-jekyll) to create a microsite.

💡 Export [Carbon](#-exporting-carbon-code-snippets) code snippets for given Xcode Playgrounds.


💻 Installation

📟 Using Homebrew (preferred)

It will warn you if there is a missing dependency and will provide guidance to install it.

📦 Using Swift Package Manager

nef can be consumed as a library in your macOS project.

.package(url: "https://github.com/bow-swift/nef.git", from: "{version}")

You can read more about how to use nef library in the nef site.


🔌 Using Xcode Editor Extension

Some of the nef features can be used directly in Xcode as an Extension. You can install it directly from App Store.



📃 Creating an Xcode Playground

Xcode Playgrounds are a nice tool for prototyping and trying new concepts. However, third party libraries support is a bit cumbersome to add. One of the goals of nef is to make the creation of an Xcode Playground easier with support for one or more libraries.

By default, nef can create an Xcode Playground with support for Bow, the Functional Programming companion library for Swift.

➜ nef playground

And you can use the following option to specify the name for the Xcode project that you are creating:

➜ nef playground --name LatestBowProject

It will create an Xcode project with support for the latest available version of Bow, named LatestBowProject. If you open this nef playground, you will have an Xcode Playground where you can import Bow or any of its modules, and start trying some of its features.

By default, nef playground will be created for iOS platform. If you need to change it, you can use the --platform option.

➜ nef playground --platform osx

📣 You can select any different Bow version or branch, even a third-party dependency

Note: The next three options are mutually exclusive.

  • --bow-version <x.y.z>: Specify the version of Bow that you want to use in the project. This option lets you test an old version of the library in an Xcode Playground. Example:
➜ nef playground --name OldBowProject --bow-version 0.3.0
  • --bow-branch <branch-name>: Specify the branch of Bow that you want to use in the project. This option lets you test features of Bow that are still in development in a branch that has not been merged or released yet. Example:
➜ nef playground --name BranchBowProject --bow-branch master
  • --podfile <Podfile>: Specify a Podfile with your own dependencies. This option lets you create a Playground with support for other libraries. Create a Podfile listing your dependencies and pass it to nef. Example:

Your Podfile, located in ./folder/dependencies:

target 'MyPodsProject' do
  platform :osx, '10.14'

  pod 'Bow', '~> 0.3.0'
➜ nef playground --name MyPodsProject --podfile ./folder/dependencies/Podfile
  • --cartfile <Cartfile>: Specify a Cartfile with your dependencies. Create a Cartfile listing your dependencies and pass it to nef. Example:

Your Cartfile, located in ./folder/dependencies:

github "bow-swift/Bow"
➜ nef playground --name MyCarthageProject --cartfile ./folder/dependencies/Cartfile


🔨 Compiling an Xcode Playground

Xcode lets you check for correctness of your Xcode Playground and run it. However, compiling an Xcode Playground from the command line is not so easy when it has dependencies on third-party libraries. This is particularly useful in Continuous Integration when you want to verify that your playgrounds are not broken when the libraries you depend on are updated. nef has an option to compile Xcode Playgrounds in an Xcode project with dependencies. To do this, you can run the following command:

➜ nef compile <path>

Where <path> is the path to the folder where the project and playgrounds are located. You can use the following option with this command:

  • --use-cache: Use cached dependencies if it is possible, in another case, it will download them. Example:
➜ nef compile <path> --use-cache

You can also clean the result of the compilation:

➜ nef clean <path>


📲 Creating a Playground Book

Swift Playgrounds is a revolutionary app that makes possible to write Swift code on an iPad. In the latest updates, Swift Playgrounds 3.x has added a new feature: UserModules; it lets you include swift code and make it available across multiple chapters like modules.

nef takes advantage of these new possibilities and advancements in Swift Package Manager to build a Playground Book with external dependencies from a Swift Package specification.

Given a Package.swift like the next one:

// swift-tools-version:5.0

import PackageDescription

let package = Package(
    name: "BowTestProject",
    dependencies: [
        .package(url: "https://github.com/bow-swift/bow.git", from: "0.7.0"),

you can run the following command:

➜ nef ipad --name PlaygroundName --package Package.swift --output ~/Desktop

It will create a Playground Book (PlaygroundName) with support for the external dependencies and save it in ~/Desktop


  • --name: the name for the Playground Book to build.
  • --package: path to the Swift Package specification.
  • --output: path where the resulting Playground Book will be generated.


🔖 Generating a Markdown project

Xcode Playgrounds let you write comments in Markdown format using the symbols //: for single line comments, or /*: */ for multiline comments. Inside these comments, you can use any Markdown syntax; an example:

 # This is a heading 1

 This is regular text. *This is bold text*. [This is a link](http://bow-swift.io).
protocol MyProtocol {}

//: ## This is a single line heading 2

It makes Xcode Playgrounds the proper tool to write an article with compilable examples. The command provided by nef to generate the Markdown files is:

➜ nef markdown --project <path-to-input> --output <path-to-output>


  • --project: Path to the folder containing the Xcode project with Xcode Playgrounds.
  • --output: Path where the resulting Markdown project will be generated.


🌐 Generating Markdown files for Jekyll

As you can write comments in Markdown in Xcode Playgrounds, this makes it very suitable to write documentation with compilable examples. Leveraging this, nef can create Markdown files that can be consumed from Jekyll to generate a microsite. The command to do this is:

➜ nef jekyll --project <path-to-input> --output <path-to-output> --main-page <path-to-index>


  • --project: Path to the folder containing the Xcode project with Xcode Playgrounds.
  • --output: Path where the resulting Markdown files will be generated.
  • --main-page: Optional. Path to a README.md file to be used as the index page of the generated microsite.

📣 How to setup an Xcode Playgroud for Jekyll?

nef finds all the Xcode Playgrounds in an Xcode project. Each playground is considered a section in the generated microsite structure. For each page in a playground, an entry in the corresponding section is created. The page is transformed from Swift to Markdown using the syntax described above. As a result, a directory structure matching the Xcode project structure is generated, together with a sidebar.yml that can be used as a menu in Jekyll.

nef adds some commands to modify the Markdown transformation process. All nef commands are included as Swift comments. They begin with // nef:begin: and end with // nef:end. The supported commands are:

  • header: It lets you add metadata to a playground page to be consumed by Jekyll. You must provide the layout that this page will use in Jekyll. The remaining attributes are optional, and you may include any of them according to your Jekyll configuration. nef will take care of the permalinks as well. Example (at the beginning of the playground page):
// nef:begin:header
  layout: docs
// nef:end
  • hidden: It lets you hide a portion of your playground in the output Markdown file. It is useful to hide imports or supporting utility code to make an example work. Example:
// nef:begin:hidden
import Bow // This will be hidden in the Markdown file
// nef:end

struct Person {} // This will be present in the Markdown file


🌁 Exporting Carbon code snippets

Xcode Playgrounds are a great place for prototyping and trying new concepts. Oftentimes we want to share some Swift snippets. Carbon is a cool tool for this, and nef nicely integrates with it. You can take your Xcode Playground, write several pieces of code, and keep it verified. Later, you can export all your code snippets with the next command:

➜ nef carbon --project <path-to-input> --output <path-to-output>


  • --project: Path to the folder containing the Xcode project with Xcode Playgrounds.
  • --output: Path where the resulting Carbon snippets will be generated.

📣 You can customize the output with the next commands

Command Description Format Options Default --background Background color applied to image hexadecimal #AABBCC, #AABBCCDD or predefined colors nef bow white green blue yellow orange nef --theme Carbon's theme to be applied String cobalt blackboard dracula duotone hopscotch lucario material monokai nord oceanicNext oneDark panda paraiso seti purple solarized tomorrow twilight verminal vscode zenburn dracula --size Export file dimensions Number [1, 5] 2 --font Font type String firaCode hack inconsolata iosevka monoid anonymous sourceCodePro darkMono droidMono fantasqueMono ibmPlexMono spaceMono ubuntuMono firaCode --lines shows/hides number of lines in code snippet Bool true false true --watermark shows/hides watermark in code snippet Bool true false true

Example of use

If we have a project created by nef, and an Xcode playground with the next content:

let example = "This is an example"
print("nef is super cool: \(example)")

// nef is super cool: This is an example

Running the following command, we will customize the background color to #d54048 bow, hide the number of lines, and set the export file to size 3:

➜ nef carbon --project . --output ~/Desktop/nef-carbon --background bow --size 3 --lines false


❤️ Contributing to the project

You can contribute in different ways to make nef better:

  • File an issue if you encounter a bug or malfunction in nef.
  • Suggest a new use case or feature for nef.
  • Open a Pull Request fixing a problem or adding new functionality.
  • Discuss with us in the Gitter channel for Bow about all the above.


⚖️ License

Copyright (C) 2019 The nef Authors

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at


Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
See the License for the specific language governing permissions and
limitations under the License.

*Note that all licence references and agreements mentioned in the nef README section above are relevant to that project's source code only.