diff --git a/docs/android.md b/docs/android.md
new file mode 100644
index 000000000..e0bc36d30
--- /dev/null
+++ b/docs/android.md
@@ -0,0 +1,107 @@
+Using KICL on Android
+=====================
+
+KICL can be used within an Android application. This requires some configuration, because KICL uses features only available in Java 8:
+
+### Add the library dependency
+
+In `app/build.gradle`:
+
+```groovy
+dependencies {
+ // ...
+ implementation group: 'org.kitteh.irc', name: 'client-lib', version: '5.1.0'
+}
+```
+
+### Ensure minSdkVersion >= 24
+
+In `app/build.gradle`:
+
+```groovy
+android {
+ // ...
+ defaultConfig {
+ applicationId "com.example.kiclandoridtest"
+ minSdkVersion 24
+ // ...
+ }
+}
+
+### Ensure source and target compatibility are set for Java 8
+
+In `app/build.gradle`:
+
+```groovy
+android {
+ // ...
+ compileOptions {
+ sourceCompatibility = '1.8'
+ targetCompatibility = '1.8'
+ }
+}
+```
+
+### Filter out duplicate META-INF files
+
+In `app/build.gradle`:
+
+```groovy
+android {
+ // ...
+ packagingOptions {
+ exclude 'META-INF/INDEX.LIST'
+ exclude 'META-INF/io.netty.versions.properties'
+ }
+}
+```
+
+### Add internet permission
+
+In `AndroidManifest.xml`:
+
+```xml
+
+
+
+
+```
+
+### Write some code
+
+Simple asynchronous task to connect to an IRC network and send a message:
+
+```java
+package com.example.kiclandoridtest;
+
+import android.os.AsyncTask;
+
+import org.kitteh.irc.client.library.Client;
+
+public class ConnectIrcTask extends AsyncTask {
+ @Override
+ protected Void doInBackground(Void... voids) {
+ Client client = Client.builder().nick("KittehAndroid").server().host("irc.esper.net").then().buildAndConnect();
+
+ client.addChannel("#kittehandroid");
+ client.sendMessage("#kittehandroid", "Hello World!");
+ return null;
+ }
+}
+```
+
+
+And run it somewhere in an activity listener:
+
+```java
+FloatingActionButton fab = findViewById(R.id.fab);
+fab.setOnClickListener(new View.OnClickListener() {
+ @Override
+ public void onClick(View view) {
+ Snackbar.make(view, "Connecting to IRC", Snackbar.LENGTH_LONG)
+ .setAction("Action", null).show();
+ new ConnectIrcTask().execute();
+ }
+});
+```
diff --git a/mkdocs.yml b/mkdocs.yml
index 00797a945..8b1c5ffe6 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -4,6 +4,7 @@ pages:
- Home: index.md
- Events: events.md
- IRCv3 Support: ircv3.md
+- Using with Android: android.md
- Advanced:
- Account Tracking: advanced/accounts.md
- SSL: advanced/ssl.md