Kickstart documentation

README.md

@@ -22,7 +22,7 @@
 
 Azimutt is a full-stack database exploration tool, from modern ERD made for real world databases (big & messy), to fast data navigation, but also documentation everywhere and whole database analysis.
 
-[![Azimutt screenshot](docs/_assets/azimutt.png)](https://azimutt.app/45f571a6-d9b8-4752-8a13-93ac0d2b7984/c00d0c45-8db2-46b7-9b51-eba661640c3c?token=59166798-32de-4f46-a1b4-0f7327a91336)
+[![Azimutt screenshot](assets/azimutt-screenshot.png)](https://azimutt.app/45f571a6-d9b8-4752-8a13-93ac0d2b7984/c00d0c45-8db2-46b7-9b51-eba661640c3c?token=59166798-32de-4f46-a1b4-0f7327a91336)
 
 **Why building Azimutt?**
 
@@ -36,9 +36,7 @@ So we decided to built it 💪
 
 Azimutt started as a schema exploration tool for databases with hundreds of tables, but now it has grown a lot:
 
-[![Azimutt roadmap](docs/_assets/roadmap.png)](https://mm.tt/map/2434161843?t=N2yWZj1pc1)
-
-- Design your schema using [AML](libs/aml/README.md) for a fast diagramming
+- Design your schema using [AML](https://azimutt.app/aml) for a fast diagramming
 - Explore your database schema using search everywhere, display only useful tables/columns and follow relations
 - Query your data like never before, follow foreign keys and display entities in diagram
 - Document using table/column notes and tags and layouts and memos for use cases, features or team scopes

backend/lib/azimutt.ex

@@ -327,4 +327,64 @@ defmodule Azimutt do
       %{id: "amlv1", name: "AMLv1", parse: true, generate: true}
     ]
   end
+
+  def doc_pages do
+    # slugs must be unique and not change as they are used for urls (SEO) and template names.
+    [
+      %{slug: "what-is-azimutt", name: "What is Azimutt?"},
+      %{
+        slug: "getting-started",
+        name: "Getting started",
+        children: [
+          %{slug: "create-your-project", name: "Create your project", children: [%{slug: "export-your-database-schema", name: "Export your database schema"}]},
+          %{
+            slug: "schema-exploration",
+            name: "Schema exploration",
+            children: [
+              %{slug: "search", name: "Search"},
+              %{slug: "follow-relations", name: "Follow relations"},
+              %{slug: "find-path", name: "Find path"}
+            ]
+          },
+          %{slug: "schema-documentation", name: "Schema documentation"},
+          %{slug: "database-design", name: "Database design"}
+        ]
+      },
+      %{
+        slug: "main-features",
+        name: "Main features",
+        children: [
+          %{slug: "layouts", name: "Layouts"},
+          %{slug: "sources", name: "Sources"},
+          %{slug: "data-exploration", name: "Data exploration"},
+          %{slug: "database-analysis", name: "Database analysis"},
+          %{slug: "keyboard-shortcuts", name: "Keyboard shortcuts"},
+          %{slug: "collaboration", name: "Collaboration"},
+          %{slug: "export", name: "Export"},
+          %{slug: "project-settings", name: "Project settings"},
+          %{slug: "api", name: "API"}
+        ]
+      },
+      %{
+        slug: "other-tools",
+        name: "Other tools",
+        children: [
+          %{slug: "cli", name: "CLI"},
+          %{slug: "converters", name: "Converters"}
+        ]
+      },
+      %{slug: "installation", name: "Installation"},
+      %{slug: "data-privacy", name: "Data privacy", details: "how Azimutt keep your data safe"}
+    ]
+  end
+
+  def doc_pages_flat, do: doc_pages() |> flatten_pages()
+
+  defp flatten_pages(pages, parents \\ []) do
+    pages
+    |> Enum.flat_map(fn page ->
+      children = if page[:children], do: page.children |> flatten_pages(parents ++ [page]), else: []
+      [page |> Map.put(:parents, parents) | children]
+    end)
+  end
 end

backend/lib/azimutt_web.ex

@@ -29,15 +29,12 @@ defmodule AzimuttWeb do
 
   def view do
     quote do
-      use Phoenix.View,
-        root: "lib/azimutt_web/templates",
-        namespace: AzimuttWeb
+      use Phoenix.View, root: "lib/azimutt_web/templates", pattern: "**/*", namespace: AzimuttWeb
 
       alias AzimuttWeb.Components.Icon
 
       # Import convenience functions from controllers
-      import Phoenix.Controller,
-        only: [get_flash: 1, get_flash: 2, view_module: 1, view_template: 1]
+      import Phoenix.Controller, only: [get_flash: 1, get_flash: 2, view_module: 1, view_template: 1]
 
       # Include shared imports and aliases for views
       unquote(view_helpers())

backend/lib/azimutt_web/components/icon.ex

@@ -72,6 +72,7 @@ defmodule AzimuttWeb.Components.Icon do
       "rectangle-stack" -> rectangle_stack(assigns)
       "rocket-launch" -> rocket_launch(assigns)
       "server-stack" -> server_stack(assigns)
+      "slash" -> slash(assigns)
       "sparkles" -> sparkles(assigns)
       "shield-check" -> shield_check(assigns)
       "shopping-cart" -> shopping_cart(assigns)
@@ -1480,6 +1481,27 @@ defmodule AzimuttWeb.Components.Icon do
     end
   end
 
+  def slash(assigns) do
+    classes = if assigns[:class], do: " #{assigns[:class]}", else: ""
+
+    case assigns[:kind] do
+      "outline" ->
+        ~H"""
+        <.outline classes={classes}><path stroke-linecap="round" stroke-linejoin="round" d="m9 20.247 6-16.5" /></.outline>
+        """
+
+      "solid" ->
+        ~H"""
+        <.solid classes={classes}><path fill-rule="evenodd" d="M15.256 3.042a.75.75 0 0 1 .449.962l-6 16.5a.75.75 0 1 1-1.41-.513l6-16.5a.75.75 0 0 1 .961-.449Z" clip-rule="evenodd" /></.solid>
+        """
+
+      _ ->
+        ~H"""
+        <.mini classes={classes}><path fill-rule="evenodd" d="M12.528 3.047a.75.75 0 0 1 .449.961L8.433 16.504a.75.75 0 1 1-1.41-.512l4.544-12.496a.75.75 0 0 1 .961-.449Z" clip-rule="evenodd" /></.mini>
+        """
+    end
+  end
+
   def shield_check(assigns) do
     classes = if assigns[:class], do: " #{assigns[:class]}", else: ""
 

backend/lib/azimutt_web/controllers/website_controller.ex

@@ -27,13 +27,13 @@ defmodule AzimuttWeb.WebsiteController do
   end
 
   def aml(conn, _params), do: conn |> render("aml.html")
-  def converters(conn, _params), do: conn |> render("converters.html")
+  def converters(conn, _params), do: conn |> render("converters/index.html")
 
   def converter(conn, %{"from" => from}) do
     Azimutt.converters()
     |> Enum.find(fn c -> c.id == from end)
     |> Result.from_nillable()
-    |> Result.map(fn converter -> conn |> render("converter.html", converter: converter) end)
+    |> Result.map(fn converter -> conn |> render("converters/converter.html", converter: converter) end)
   end
 
   def convert(conn, %{"from" => from_id, "to" => to_id}) do
@@ -42,12 +42,26 @@ defmodule AzimuttWeb.WebsiteController do
 
     from_converter
     |> Result.flat_map(fn f -> to_converter |> Result.map(fn t -> {f, t} end) end)
-    |> Result.map(fn {from, to} -> conn |> render("convert.html", from: from, to: to) end)
+    |> Result.map(fn {from, to} -> conn |> render("converters/convert.html", from: from, to: to) end)
   end
 
   def portal(conn, _params), do: conn |> render("portal.html")
   def portal_subscribed(conn, _params), do: conn |> render("portal-subscribed.html")
 
+  def docs(conn, _params),
+    do: conn |> render("docs/index.html", page: %{slug: "index", name: "Azimutt Documentation", children: Azimutt.doc_pages(), parents: []}, prev: nil, next: nil)
+
+  def doc(conn, %{"slug" => slug}) do
+    pages = Azimutt.doc_pages_flat()
+
+    pages
+    |> Enum.find_index(fn p -> p.slug == slug end)
+    |> Result.from_nillable()
+    |> Result.map(fn index ->
+      conn |> render("docs/#{slug}.html", page: pages |> Enum.at(index), prev: if(index > 0, do: pages |> Enum.at(index - 1), else: nil), next: pages |> Enum.at(index + 1))
+    end)
+  end
+
   def last(conn, _params) do
     case conn |> last_used_project do
       {:ok, p} -> conn |> redirect(to: Routes.elm_path(conn, :project_show, p.organization_id, p.id))
@@ -65,24 +79,24 @@ defmodule AzimuttWeb.WebsiteController do
     conn |> get_req_header("referer") |> Enum.any?(fn h -> h |> String.contains?(Azimutt.config(:host)) end)
   end
 
-  def use_cases_index(conn, _params), do: conn |> render("use-cases.html")
+  def use_cases_index(conn, _params), do: conn |> render("use-cases/index.html")
 
   def use_cases_show(conn, %{"use_case_id" => use_case_id}) do
     Azimutt.showcase_usages()
     |> Enum.find(fn u -> u.id == use_case_id end)
     |> Result.from_nillable()
-    |> Result.map(fn use_case -> conn |> render("use-case-#{use_case_id}.html", use_case: use_case) end)
+    |> Result.map(fn use_case -> conn |> render("use-cases/#{use_case_id}.html", use_case: use_case) end)
   end
 
-  def features_index(conn, _params), do: conn |> render("features.html")
+  def features_index(conn, _params), do: conn |> render("features/index.html")
 
   def features_show(conn, %{"feature_id" => feature_id}) do
     Azimutt.showcase_features()
     |> Enum.find_index(fn f -> f.id == feature_id end)
     |> Result.from_nillable()
     |> Result.map(fn index ->
       conn
-      |> render("feature-#{feature_id}.html",
+      |> render("features/#{feature_id}.html",
         feature: Azimutt.showcase_features() |> Enum.at(index),
         previous: if(index > 0, do: Azimutt.showcase_features() |> Enum.at(index - 1), else: nil),
         next: Azimutt.showcase_features() |> Enum.at(index + 1)

backend/lib/azimutt_web/router.ex

@@ -54,6 +54,8 @@ defmodule AzimuttWeb.Router do
     get("/converters", WebsiteController, :converters)
     get("/converters/:from", WebsiteController, :converter)
     get("/converters/:from/to/:to", WebsiteController, :convert)
+    get("/docs", WebsiteController, :docs)
+    get("/docs/:slug", WebsiteController, :doc)
     get("/last", WebsiteController, :last)
     get("/use-cases", WebsiteController, :use_cases_index)
     get("/use-cases/:use_case_id", WebsiteController, :use_cases_show)

backend/lib/azimutt_web/templates/blog/_blog_footer.html.heex

@@ -7,17 +7,17 @@
         </div>
     </div>
     <div class="flex justify-center pt-4 space-x-4 align-center">
-        <a href={Azimutt.config(:azimutt_github)} rel="noopener noreferrer" aria-label="GitHub" class="p-2 rounded-md">
+        <a href={Azimutt.config(:azimutt_github)} target="_blank" rel="noopener noreferrer" aria-label="GitHub" class="p-2 rounded-md">
             <svg viewBox="0 0 496 512" xmlns="http://www.w3.org/2000/svg" class="w-4 h-4 fill-current">
                 <path d="M165.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6zm-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3zm44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9zM244.8 8C106.1 8 0 113.3 0 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C428.2 457.8 496 362.9 496 252 496 113.3 383.5 8 244.8 8zM97.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1zm-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7zm32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1zm-11.4-14.7c-1.6 1-1.6 3.6 0 5.9 1.6 2.3 4.3 3.3 5.6 2.3 1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2z"></path>
             </svg>
         </a>
-        <a href={Azimutt.config(:azimutt_twitter)} rel="noopener noreferrer" aria-label="Twitter" class="p-2 rounded-md">
+        <a href={Azimutt.config(:azimutt_twitter)} target="_blank" rel="noopener noreferrer" aria-label="Twitter" class="p-2 rounded-md">
             <svg viewBox="0 0 512 512" xmlns="http://www.w3.org/2000/svg" class="w-4 h-4 fill-current">
                 <path d="M459.37 151.716c.325 4.548.325 9.097.325 13.645 0 138.72-105.583 298.558-298.558 298.558-59.452 0-114.68-17.219-161.137-47.106 8.447.974 16.568 1.299 25.34 1.299 49.055 0 94.213-16.568 130.274-44.832-46.132-.975-84.792-31.188-98.112-72.772 6.498.974 12.995 1.624 19.818 1.624 9.421 0 18.843-1.3 27.614-3.573-48.081-9.747-84.143-51.98-84.143-102.985v-1.299c13.969 7.797 30.214 12.67 47.431 13.319-28.264-18.843-46.781-51.005-46.781-87.391 0-19.492 5.197-37.36 14.294-52.954 51.655 63.675 129.3 105.258 216.365 109.807-1.624-7.797-2.599-15.918-2.599-24.04 0-57.828 46.782-104.934 104.934-104.934 30.213 0 57.502 12.67 76.67 33.137 23.715-4.548 46.456-13.32 66.599-25.34-7.798 24.366-24.366 44.833-46.132 57.827 21.117-2.273 41.584-8.122 60.426-16.243-14.292 20.791-32.161 39.308-52.628 54.253z"></path>
             </svg>
         </a>
-        <a href={"mailto:#{Azimutt.config(:contact_email)}"} rel="noopener noreferrer" aria-label="Email" class="p-2 rounded-md">
+        <a href={"mailto:#{Azimutt.config(:contact_email)}"} target="_blank" rel="noopener noreferrer" aria-label="Email" class="p-2 rounded-md">
             <svg viewBox="0 0 512 512" xmlns="http://www.w3.org/2000/svg" class="w-4 h-4 fill-current">
                 <path d="M464 64H48C21.49 64 0 85.49 0 112v288c0 26.51 21.49 48 48 48h416c26.51 0 48-21.49 48-48V112c0-26.51-21.49-48-48-48zm0 48v40.805c-22.422 18.259-58.168 46.651-134.587 106.49-16.841 13.247-50.201 45.072-73.413 44.701-23.208.375-56.579-31.459-73.413-44.701C106.18 199.465 70.425 171.067 48 152.805V112h416zM48 400V214.398c22.914 18.251 55.409 43.862 104.938 82.646 21.857 17.205 60.134 55.186 103.062 54.955 42.717.231 80.509-37.199 103.053-54.947 49.528-38.783 82.032-64.401 104.947-82.653V400H48z"></path>
             </svg>

backend/lib/azimutt_web/templates/clever_cloud/error_member_limit_reached.html.heex

@@ -14,7 +14,7 @@
                 </div>
                 <div class="mt-10 flex space-x-3 sm:border-l sm:border-transparent sm:pl-6">
                     <a href={CleverCloud.addon_settings_url(@resource.owner_id, @resource.addon_id)} class="inline-flex items-center rounded-md border border-transparent bg-indigo-600 px-4 py-2 text-sm font-medium text-white shadow-sm hover:bg-indigo-700 focus:outline-none focus:ring-2 focus:ring-indigo-500 focus:ring-offset-2">Go back to Clever Cloud</a>
-                    <a href={"mailto:#{Azimutt.config(:support_email)}"} rel="noopener noreferrer" class="inline-flex items-center rounded-md border border-transparent bg-indigo-100 px-4 py-2 text-sm font-medium text-indigo-700 hover:bg-indigo-200 focus:outline-none focus:ring-2 focus:ring-indigo-500 focus:ring-offset-2">Contact us</a>
+                    <a href={"mailto:#{Azimutt.config(:support_email)}"} target="_blank" rel="noopener noreferrer" class="inline-flex items-center rounded-md border border-transparent bg-indigo-100 px-4 py-2 text-sm font-medium text-indigo-700 hover:bg-indigo-200 focus:outline-none focus:ring-2 focus:ring-indigo-500 focus:ring-offset-2">Contact us</a>
                 </div>
             </div>
         </main>

backend/lib/azimutt_web/templates/clever_cloud/show.html.heex

@@ -46,7 +46,7 @@
                                             <div class="sm:flex">
                                                 <div class="min-w-0 flex-1">
                                                     <label for="database" class="sr-only">Database URI</label>
-                                                    <input type="text" name="database" id="database" placeholder="Enter your database URI" required class="block w-full rounded-md border-0 px-4 py-3 text-base text-gray-900 placeholder-gray-500 focus:outline-none focus:ring-2 focus:ring-indigo-300 focus:ring-offset-2 focus:ring-offset-gray-900">
+                                                    <input type="password" name="database" id="database" placeholder="Enter your database URI" required class="block w-full rounded-md border-0 px-4 py-3 text-base text-gray-900 placeholder-gray-500 focus:outline-none focus:ring-2 focus:ring-indigo-300 focus:ring-offset-2 focus:ring-offset-gray-900">
                                                 </div>
                                                 <div class="mt-3 sm:mt-0 sm:ml-3">
                                                     <button type="submit" class="bg-[#d74d4e] hover:bg-[#bf2b2c] block w-full rounded-md py-3 px-4 font-medium text-white shadow focus:outline-none focus:ring-2 focus:ring-indigo-300 focus:ring-offset-2 focus:ring-offset-gray-900">Connect database</button>

backend/lib/azimutt_web/templates/heroku/error_member_limit_reached.html.heex

@@ -14,7 +14,7 @@
                 </div>
                 <div class="mt-10 flex space-x-3 sm:border-l sm:border-transparent sm:pl-6">
                     <a href={Heroku.app_addons_url(@heroku_app)} class="inline-flex items-center rounded-md border border-transparent bg-indigo-600 px-4 py-2 text-sm font-medium text-white shadow-sm hover:bg-indigo-700 focus:outline-none focus:ring-2 focus:ring-indigo-500 focus:ring-offset-2">Go back to Heroku</a>
-                    <a href={"mailto:#{Azimutt.config(:support_email)}"} rel="noopener noreferrer" class="inline-flex items-center rounded-md border border-transparent bg-indigo-100 px-4 py-2 text-sm font-medium text-indigo-700 hover:bg-indigo-200 focus:outline-none focus:ring-2 focus:ring-indigo-500 focus:ring-offset-2">Contact us</a>
+                    <a href={"mailto:#{Azimutt.config(:support_email)}"} target="_blank" rel="noopener noreferrer" class="inline-flex items-center rounded-md border border-transparent bg-indigo-100 px-4 py-2 text-sm font-medium text-indigo-700 hover:bg-indigo-200 focus:outline-none focus:ring-2 focus:ring-indigo-500 focus:ring-offset-2">Contact us</a>
                 </div>
             </div>
         </main>

backend/lib/azimutt_web/templates/heroku/error_too_many_members.html.heex

@@ -14,7 +14,7 @@
                 </div>
                 <div class="mt-10 flex space-x-3 sm:border-l sm:border-transparent sm:pl-6">
                     <a href={Heroku.app_addons_url(@heroku_app)} class="inline-flex items-center rounded-md border border-transparent bg-indigo-600 px-4 py-2 text-sm font-medium text-white shadow-sm hover:bg-indigo-700 focus:outline-none focus:ring-2 focus:ring-indigo-500 focus:ring-offset-2">Go back to Heroku</a>
-                    <a href={"mailto:#{Azimutt.config(:support_email)}"} rel="noopener noreferrer" class="inline-flex items-center rounded-md border border-transparent bg-indigo-100 px-4 py-2 text-sm font-medium text-indigo-700 hover:bg-indigo-200 focus:outline-none focus:ring-2 focus:ring-indigo-500 focus:ring-offset-2">Contact us</a>
+                    <a href={"mailto:#{Azimutt.config(:support_email)}"} target="_blank" rel="noopener noreferrer" class="inline-flex items-center rounded-md border border-transparent bg-indigo-100 px-4 py-2 text-sm font-medium text-indigo-700 hover:bg-indigo-200 focus:outline-none focus:ring-2 focus:ring-indigo-500 focus:ring-offset-2">Contact us</a>
                 </div>
             </div>
         </main>