New docs

docs/contact.mdx

@@ -0,0 +1,15 @@
+---
+title: "Contact Us"
+---
+
+BAML is here to serve its users: we always want to hear your feedback, whether
+it's a bug, feature request, or just general comment.
+
+You can reach us using:
+
+    - [Discord](/discord) (fastest for a "how do i... ?")
+    - [GitHub](https://github.com/BoundaryML/baml/issues) (for bugs and feature requests)
+    - Email: [[email protected]](mailto:[email protected])
+    - Twitter: [@boundaryml](https://twitter.com/boundaryml)
+
+We try our best to respond as quickly as possible, so don't hesitate to reach out!

docs/docs/calling-baml/calling-functions.mdx

@@ -0,0 +1,106 @@
+---
+title: "Calling BAML Functions"
+---
+
+Once you've [generated the BAML client] and set your environment variables,
+you can call BAML functions from your code.
+
+<Tip>You can check out more examples in the [BAML Examples] repo.</Tip>
+
+[generated the BAML client]: /docs/calling-baml/generate-baml-client
+[BAML Examples]: https://github.com/BoundaryML/baml-examples/tree/main
+
+We’ll use `function ClassifyMessage(input: string) -> Category` for our example:
+
+<Accordion title="classify-message.baml">
+```rust
+enum Category {
+    Refund
+    CancelOrder
+    TechnicalSupport
+    AccountIssue
+    Question
+}
+
+function ClassifyMessage(input: string) -> Category {
+  client GPT4o
+  prompt #"
+    Classify the following INPUT into ONE
+    of the following categories:
+
+    INPUT: {{ input }}
+
+    {{ ctx.output_format }}
+
+    Response:
+  "#
+}
+```
+</Accordion>
+
+<Tabs>
+<Tab title="Python">
+
+BAML will generate `b.ClassifyMessage()` for you, which you can use like so:
+
+```python main.py
+import asyncio
+
+from baml_client import b
+from baml_client.types import Category
+
+async def main():
+    category = await b.ClassifyMessage("I want to cancel my order")
+    print(category)
+    assert category == Category.CancelOrder
+
+if __name__ == '__main__':
+    asyncio.run(main())
+```
+</Tab>
+
+<Tab title="TypeScript">
+
+BAML will generate `b.ClassifyMessage()` for you, which you can use like so:
+
+```ts main.ts
+import { b } from './baml_client'
+import { Category } from './baml_client/types'
+import assert from 'assert'
+
+const main = async () => {
+  const category = await b.ClassifyMessage('I want to cancel my order')
+  console.log(category)
+  assert(category == Category.CancelOrder)
+}
+
+if (require.main === module) {
+  main()
+}
+
+```
+</Tab>
+
+<Tab title="Ruby">
+
+BAML will generate `Baml.Client.ClassifyMessage()` for you, which you can use like so:
+
+```ruby main.rb
+require_relative "baml_client/client"
+
+$b = Baml.Client
+
+def main
+    category = $b.ClassifyMessage(input: "I want to cancel my order")
+    puts category
+    category == Baml::Types::Category::CancelOrder
+end
+
+if __FILE__ == $0
+  puts main
+end
+
+```
+
+</Tab>
+</Tabs>

docs/docs/calling-baml/concurrent-calls.mdx

@@ -0,0 +1,85 @@
+---
+title: "Concurrent function calls"
+---
+
+We’ll use `function ClassifyMessage(input: string) -> Category` for our example:
+
+<Accordion title="classify-message.baml">
+```rust
+enum Category {
+    Refund
+    CancelOrder
+    TechnicalSupport
+    AccountIssue
+    Question
+}
+
+function ClassifyMessage(input: string) -> Category {
+  client GPT4o
+  prompt #"
+    Classify the following INPUT into ONE
+    of the following categories:
+
+    INPUT: {{ input }}
+
+    {{ ctx.output_format }}
+
+    Response:
+  "#
+}
+```
+</Accordion>
+
+<Tabs>
+<Tab title="Python">
+
+You can make concurrent `b.ClassifyMessage()` calls like so:
+
+```python main.py
+import asyncio
+
+from baml_client import b
+from baml_client.types import Category
+
+async def main():
+    await asyncio.gather(
+        b.ClassifyMessage("I want to cancel my order"),
+        b.ClassifyMessage("I want a refund")
+    )
+
+if __name__ == '__main__':
+    asyncio.run(main())
+```
+</Tab>
+
+<Tab title="TypeScript">
+
+You can make concurrent `b.ClassifyMessage()` calls like so:
+
+```ts main.ts
+import { b } from './baml_client'
+import { Category } from './baml_client/types'
+import assert from 'assert'
+
+const main = async () => {
+  const category = await Promise.all(
+    b.ClassifyMessage('I want to cancel my order'),
+    b.ClassifyMessage('I want a refund'),
+  )
+}
+
+if (require.main === module) {
+  main()
+}
+
+```
+</Tab>
+
+<Tab title="Ruby">
+
+BAML Ruby does not currently support async/concurrent calls.
+
+Please [contact us](/contact) if this is something you need.
+
+</Tab>
+</Tabs>

docs/docs/calling-baml/generate-baml-client.mdx

@@ -0,0 +1,133 @@
+---
+title: "Generate the BAML Client"
+---
+
+<Info>This page assumes you've already defined a function in BAML. If you
+haven't done that yet, check out [how to define a function].</Info>
+
+[how to define a function]: /docs/snippets/functions
+
+Once you've defined a function in BAML, you need to generate code in your
+language of choice to call that function: we call this generating the BAML client.
+
+If you use VSCode, the [BAML extension] will re-generate the client every time
+you save a BAML file. Otherwise, you can generate the client manually:
+
+[BAML extension]: https://marketplace.visualstudio.com/items?itemName=Boundary.baml-extension
+
+<CodeGroup>
+
+```bash Python
+pipx run baml-cli generate --from path/to/baml_src
+
+# If using your local installation, venv or conda:
+pip install baml-py
+baml-cli generate --from path/to/baml_src
+
+# If using poetry:
+poetry add baml-py
+poetry run baml-cli generate --from path/to/baml_src
+
+# If using pipenv:
+pipenv install baml-py
+pipenv run baml-cli generate --from path/to/baml_src
+```
+
+```bash TypeScript
+npx @boundaryml/baml generate --from path/to/baml_src
+
+# If using npm:
+npm install @boundaryml/baml
+npm run baml-cli generate --from path/to/baml_src
+
+# If using pnpm:
+pnpm install @boundaryml/baml
+pnpm run baml-cli generate --from path/to/baml_src
+
+# If using pnpm:
+yarn add @boundaryml/baml
+yarn run baml-cli generate --from path/to/baml_src
+```
+
+```bash Ruby
+bundle add baml
+bundle exec baml-cli generate --from path/to/baml_src
+```
+
+</CodeGroup>
+
+## Best Practices
+
+### Define a `generator` clause
+
+<Tip>If you created your project using `baml-cli init`, then one has already been generated for you!</Tip>
+
+Each `generator` that you define in your BAML project will tell `baml-cli
+generate` to generate code for a specific target language. You can define
+multiple `generator` clauses in your BAML project, and `baml-cli generate` will
+generate code for each of them.
+
+<CodeGroup>
+
+```rust Python
+generator target {
+    // Valid values: "python/pydantic", "typescript", "ruby/sorbet"
+    output_type "python/pydantic"
+    // Where the generated code will be saved (relative to baml_src/)
+    output_dir "../"
+}
+```
+
+```rust TypeScript
+generator target {
+    // Valid values: "python/pydantic", "typescript", "ruby/sorbet"
+    output_type "typescript"
+    // Where the generated code will be saved (relative to baml_src/)
+    output_dir "../"
+}
+```
+
+```rust Python
+generator target {
+    // Valid values: "python/pydantic", "typescript", "ruby/sorbet"
+    output_type "ruby/sorbet"
+    // Where the generated code will be saved (relative to baml_src/)
+    output_dir "../"
+}
+```
+
+</CodeGroup>
+
+
+### Generate the BAML client on-demand
+
+Although you can check in the generated BAML client, we recommend that you 
+instead add it to your `.gitignore` and generate it on-demand when you
+build/release your code:
+
+  - this will make your PRs more readable;
+  - this will save you from handling merge conflicts in generated code; and
+  - this will ensure a single source-of-truth for your BAML code (and prevent
+    your client from falling out of sync with your BAML code).
+
+To add the generated client to your `.gitignore`, you can run:
+
+```bash
+echo "baml_client" >> .gitignore
+```
+
+and then you just need to run `baml-cli generate` in your CI/CD build/release
+workflows. Here's what that might look like in a GitHub Actions workflow file:
+
+```yaml
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # Install your Python/Node/Ruby dependencies here
+
+      - name: Generate BAML client
+        run: baml-cli generate --from baml_src
+```